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

From: Merrill Cornish (merrill.cornish_at_[hidden])
Date: 2006-01-30 12:10:16

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.

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?

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.

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, what you get
is a list of topics, some of which repeat with no indication
of which are subtopics of which.

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.

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.

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."

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.  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.

Merrill