Merrill Cornish 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