Re: [boost] From an user to developers

Subject: Re: [boost] From an user to developers
From: Robert Ramey (ramey_at_[hidden])
Date: 2012-06-10 17:49:50

Oodini wrote:
> Hello,
>
> I am an user, and I am currently reviewing all the Boost libraries.

I am a user also.

> But for a common user, some needs are not satisfied in the libraries
> descriptions.

This is an understatement.

> The Boost organization should compel the libraries authors to put in
> their documentation :
>
> 1. the history of all releases, with notes for each release
> 2. the motivation of their library
> 3. when they offer services similar to the ones provided by the STL,
> why did they feel the need to complete it, and what are the
> differences

many library documents have a section called "rationale" for this

> 3. for the relevant libraries, their status regarding the new
> features of C++11 (are they obsolete ? do they remain some
> differences ? ex : Array, Chrono, DateTime), especially the ones
> related to TR1

This is a problem.  What happens with a library from 10 years ago?
Is being a library developer a life sentence?  I understand the problem
but I don't see definitive solution.

The only way we "compel" authors to put things in a documentation
is through the review/approval process.  It's better than nothing but
has not been enough to improve documentation.

> An homogeneous structure for the documentation would be welcome.

I understand the motivation - but again - lot's of problems in practice.

Here is my take on the above.

a) In general, C++ Library Documentation is generally very poor and hard to
understand.  It suffers from all the above mentioned problems.  Boost
library documentation is better than most - but still very uneven
quality between libraries.

b) Although many believe that there is some sort of "formal" standard
for reference documentation there is not. There is a wide variation among
developers on what should be in documentation and what should not be.
Suggestions for documentation formats and content vary widely.  The
boost page on this subject is very hard to find.

c) The requirements for documentation varies amongst the different
types of things being documentated: types, functions, classes, concepts
templates, etc.

d) The fact that is extremely easy to identify poor documentation in
no way makes it easier to write good documentation.

e) more pages of documentation doesn't necessariliy mean that the
the documentation is better.

One thing I would suggest for the real user is to buy a few books:

a) A good C++ reference - I use The C++ programming language - Stroustrup
b) All the books by Scott Meyers
b) If you're going to use templates - C++ Templates - Vandevoorde & Josuttis
c) If you're going to even look at mpl - C++ Template Metaprogramming - 
Abrahams & Gurtovoy
d) If you're going to use STL -STL tutorial and reference -  Musser & Saini
e) If you're going to use Boost -  The Boost C++ Libraries (or similar 
book) - Boris Schäling

I realize that this sounds like a really dumb suggestion.  There are two 
facts which
jump out at me:

a) I probably consult at least one of these books every single day.
b) as a contract developer, I work at various companies.
  1) I have never seen more than one of these books at any customer site.
  2) I have had to purchase any C++ book out of my own funds.

So, there is much, much more to this problem than your question would 
suggest.

You will all be hearing much, much more from me on this topic in the near 
future.

Robert Ramey