Re: [Boost-users] Getting started with Boost: what did you need to know?

From: David Abrahams (dave_at_[hidden])
Date: 2006-02-01 18:47:26

Merrill Cornish <merrill.cornish_at_[hidden]> writes:

> David,
>
> At the risk of annoying some Boost developers...
>
> My single biggest complaint is the Boost documentation--
> not so much that the libraries are undocumented, but that
> it's so hard to find your way through the documentation that
> is provided.

I think the documentation is very uneven, and that's a problem.  The
documentation for some of the libraries is really easy to navigate,
but I think those are the exception.

> There is the documentation on the Boost site rooted under
> Libraries | Documentation.  Then there is the documentation
> under doc/html in the Boost source tree.  Then there is the
> documentation under libs/<libraryName>/doc in the source
> tree.  Sometimes, they are the same, sometimes, the libs
> documentation has extra stuff.  Why?

I don't know what you mean by "extra," but it goes like this: the
Boost source code repository contains at least four different
documentation formats:

  1. Straight HTML, authored by the library writer, in
     libs/<libraryName>/doc.  Once upon a time, all our docs were
     written by hand in HTML.

  2. ReStructuredText.  This is used to generate HTML, and sometimes,
     PDF.  Generally the resulting files are checked into the
     repository somewhere under libs/<libraryName>/doc.  

  3. BoostBook.  This is used to generate HTML, and sometimes, PDF.
     The results become one unified document (see "Nightly generated
     BoostBook documentation" at
     http://engineering.meta-comm.com/boost.aspx) and are too big to
     check into the source code repository.  They're generated
     on-the-fly and 

> A side effect of having HTML documentation is that there is
> no index--a valuable tool when you are trying find your way
> through new territory.

I don't think that's necessarily related to having HTML documentation.

> The Boost documentation standard recommends having a
> table of contents-like list of topics on the first page of a
> library's documentation.  Sounds good, but since there 
> usually isn't any paragraphing levels shown, 

Not sure what you mean.

> what you get is a list of topics, some of which repeat with no
> indication of which are subtopics of which.

Usually?  I think we're all over the map on this one, but it would
surprise me if repeated headers were the norm.

> The naming of documentation files can be misleading also.
> The discussion of mutexes (with no specific mention of
> threads) is called "thread" while the discussion of threading
> (with no specific mention of mutexes) is call "threads" [note
> the plural].  Or, maybe it's the other way around.

You mean, you're looking at the names of the HTML files?  Or you're
looking at their HTML titles?

> The available documentation takes a scatter gun approach
> at to the intended audience.  Under mutexes (whatever its
> name), there is a treatise (as I remember) on all possible
> mutex alternatives.  It's only later that the reader discovers
> none of them are actually implemented.

You should know that the threads documentation (and the library
itself) is suffering a bit from lack of maintenance.  The original
author disappeared on us and nobody has yet appeared who is really
committed to it to take his place.  I don't think you should take the
condition of the threads docs as representative of anything.

> Similarly, the serialization documentation has a long 
> discussion on shared pointers in a file named shared_ptr.html.
> Another file named shared_ptr2.html starts out by saying
> that about the stuff you just read in shared_ptr.html 
> "Unfortunately, this way of doing it suffered from some 
> undesirable features."  This is a lot like giving someone
> detailed driving directions only to say, "if you go this far,
> you've taken a wrong turn."

Yeah, that's bad.  Have you posted anything about that with
[serialization] in the subject line, to get the author's attention?
If not, don't expect it to improve.

> The documentation is written so that in order to do almost
> anything, you have to read everything, including all of the
> "here are all the wrong turns I took in developing this
> library" pages.  

So, this conclusion is from a sample of two libraries?  I haven't seen
that sort of thing anywhere myself, but I could be missing something.

> For example, the documentation for the
> serialization library seems straightforward, but you'll
> probably miss the special macro you are supposed to use
> if you are serializing an abstract class.
>
> The Boost documentation is serverly in the need of global
> editing.

Full agreement there.  We took some steps in that direction (see
http://lists.boost.org/Archives/boost/2005/10/96025.php) but I'm
afraid Mr. Stewart's other responsibilities may have overwhelmed him.
Perhaps you'd like to help out in some way?  We need people with a
keen eye for what isn't working in the docs to work on this.  Sounds
like you're qualified.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com