Re: [boost] Documentation

From: Victor A. Wagner Jr. (vawjr_at_[hidden])
Date: 2004-06-12 01:47:03

At Friday 2004-06-11 02:15, you wrote:
>Ok, if the Boost style documentation is too simple, and docs like
>Spirit are too cute, what is a nice, happy median?  If we're going
>to demand uniformity in licensing, should we also demand more
>uniformity in documentation?  I think a single documentation style
>across Boost would make it even easier to learn new libraries. I
>recently found it very difficult to find the information I wanted about
>the Boost.Test library, as well as Boost.Preprocessor.  What can
>be done about these issues?
>
>Dave

A "single style" for the documentation may be out of reach.
I _still_ haven't figured out the concept check "system" and I find that 
documentation particularly inscrutable.

Many years ago my father wrote me a letter about "volunteer 
organizations".. I'd just been elected president of an astronomy club (he 
was an officer of a square-dance club).  What he had to say applied then, 
and I think here.

In any such organization (and to a large extent this includes such ad hoc 
groups as "people using C++, boost in particular") you have the beginners 
(we call them newbies) and those who are attempting to "run" the 
organization (those who have been around for a while, and are willing to 
expend the effort to "make it better").  Unfortunately, this produces a 
conflict which can destroy the organization:  the newbies want to learn 
"basic" stuff, the old timers (some call us the old farts) want to explore 
the edges and nooks and crannies and do, sometimes, very complex stuff.

The same applies, IMO, to documentation.  The audience is (or, if you 
prefer, the audiences are) very like a club.  There are those who are just 
starting and need to learn some fundamentals (and they enjoy them).  There 
are others who have been around the block (sometimes the planet) and need 
details that only a language lawyer can love (see the ISO standard for C++ 
for an example of the latter).

Writing a single document which can serve both groups is challenge enough, 
but we have yet a third (and maybe fourth, fifth or...) group(s).  One that 
leaps to mind immediately is the person that "just needs to know 
....blah".  They want the document to be random access and contain _all_ 
the relevant information at the spot _they_ choose to look.  This requires 
that the author(s) be prescient enough to group the information in exactly 
the same manner as the presumed reader (unlikely doesn't begin to express 
the probability of _that_ happening).

Yet another difficulty is in getting people to actually READ the 
documentation.  I'm one of those weird guys that actually will read the 
documents/book/whathaveyou cover to cover (I'm not sure what that means w/ 
respect to the Spirit docs (they weren't as linear as I would have 
preferred)...but I read all of what I could find at the time).  Hyperlinks 
(yes, they're useful...immensely so) exacerbate the problem.  It's far too 
easy to get sidetracked.  The reason I try to read books front to back 
(then Langer & Kreft come along and say "read section 2 unless you're 
pretty sure you've got most of it" then continue here) is because the 
author _generally_ has a reasonably good idea of what order to present the 
information.  This is particularly important in such as our genre since so 
much of what comes later _depends_ on other things (hopefully presented 
earlier).  Sometimes even a good author (Scott Meyers leaps to mind) 
discovers that he needs to refer (with a link on the CD) to items which 
come later in the book.

What are mere mortals to do?

A fine example of documentation is Nicolai's tome "The C++ STandard 
Library  ... A Tutorial and Reference".  Right on the front cover we see 
that there are (at least) two distinct use(r)s for this document.  In 
facing a monumental task, Nicolai does more than an admirable job, yet he 
writes 799 pages (my edition) and covers _only_ (well primarily) the 
STL.  His book is the most worn of all my C++ books, and is the only book I 
rate "a must have" on my recommended reading list.
to wit:
I recommend the following books:  read them in mostly the order listed
"Accelerated C++" Andrew Koenig & Barbara Moo
"The C++ Standard Library" Nicolai Josuttis --- a "must have"
"Effective C++", "More Effective C++", "Effective STL" Scott Meyers
"Exceptional C++", "More Exceptional C++" Herb Sutter
"The C++ Programming Language" 3rd edition or later Bjarne Stroustrup
"Modern C++ Design" Andrei Alexandrescu
"C++ Templates" Vandevoorde & Josuttis
"Standard C++ IOStreams and Locales" Langer & Kreft

Do not infer that I think that the STL is small, but in comparison to the 
boost libraries, it is.  So where does that leave us (boosters)?  Difficult 
to say.  I've read the only (to my knowledge) actual _book_ about any 
portion of boost: the graph library and although I'm sure it's a very good 
book, my understanding of how to use the library still suffers.  Jeremy, 
don't take offense, the problem is mine, I knew _nothing_ about formal 
graph theory when I got the book, now I know something, but not WHERE to 
use the library, or WHY.  The book is exceptionally detailed, and likely 
quite good to someone who already knows graph theory.  This is a fine 
example (from what I can tell) of documentation for "the old guys", for a 
newbie (in this case me) it's difficult at best.

Do we need tutorials for any? some?? all??? of the libraries in 
boost?  clearly yes for any, but likely no for all (perhaps we should use 
the tribool for answer here).

Do we need reference documents?  you betcha!! At least two kinds...one for 
people USING the library, another for people who will need  to extend or 
fix the library (users _may_ not need to know the implementation details, 
maintenance folks will).  Scott Meyers says there are two audiences for 
every program... I believe that includes the documentation for every program.

Raison d'être for some libraries?  very likely.

How about some background for the problem domain?  I'd like one for 
concept-check and boost graph.

This almost leads to a conclusion that something like wikipedia or 
planetmath will be necessary to gather all the information, since the task 
appears more than one _volunteer_ author could do....even for a single 
library in the collection.

How we present it in tutorial form, I do not know.
A large problem with writing documentation post "post facto" is that the 
author(s) have spent _so_ much time completely immersed in the project and 
concepts that some very fundamental things can get left out.  Parts of the 
project have become so ingrained that the author(s) almost cannot conceive 
of "the axioms" being unknown to all.

Most of my above comments come from spending time (too much, likely) 
hanging out on IRC (Undernet #C++ channel) and attempting to help mostly 
newbies and _some_ (very few) very advanced people use the language (and 
boost).  I've also been programming professionally for 39 years and have 
written a fair number of documents on the programs I've written (I don't 
write nearly as well as _any_ of the authors of the books I recommended 
above).  I've also seen my share of poor to downright lousy documentation 
on programs that I've tried to use and or fix.

I believe it's important to have good documentation.  I've been pleased 
(mostly) with the documentation for stuff in boost (I don't even know for 
sure _all_ of what's in there any more).  Does it need "fixing"?  Well... 
I'd say the stuff _I_ can't understand certainly does, but we'll get 
different people saying different things are inscrutable.  And authors of 
those sections (correctly) stating that we newbies just don't have the 
background to appreciate the documentation.  With no pointers to _where_ 
such documentation exists, as far as we're concerned, the library might as 
well not exist.
I'll be glad to lend assistance to any updates, though my proofreading 
skills seem to be far better than my writing skills.

Victor A. Wagner Jr.      http://rudbek.com
The five most dangerous words in the English language:
               "There oughta be a law"