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"