[boost] Re: Documentation

From: Edward Diener (eddielee_at_[hidden])
Date: 2004-06-12 08:29:14

Victor A. Wagner Jr. wrote:
> At Friday 2004-06-11 02:15, you wrote:
> 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

Matt Austern's book "Generic Programming and the STL" is magnificent and,
for me, the model of how programming books should always be written. Nothing
is explained in his book before it is necessary and there is never a
reference to something which occurs later in the book and hasn't already
been discussed to some extent at least at a general level of understanding.
The care which he took to organize the book so that it is completely
understandable about a difficult subject shows on nearly every page.

Good writing on computer programming is largely a problem of good
organization when the writer is knowledgable in their subject matter. It is
a difficult task and, unfortunately, there are few technical writers who can
do it really well. Besides Mr. Austern's splendid effort, the only other
technical writer I have ever read who consistently writes books at that sort
of organizational level is Jeff Richter, who writes about Windows
programming topics. Of course all of the writers you mention have deep
knowledge of C++, but not all of them have the ability to organize their
writing as well as it could be. But of the ones I have read on your list,
all put out the effort to organize their knowledge as best as they could.
That to me is very important.

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

I would like to second your comment that their are usually two distinct
audiences. A person first learning an implementation and one who is pretty
good at it and who just needs to understand some of its nooks and crannies.
Most of the Boost documentation is excellent, and serves the purposes of
both. I am especially thinking of Mr. Gregor's documentation which addresses
different audiences by having sections labelled for the level of person who
is first approaching his implementations.

Some of it is just bewildering to the person first trying to learn the
subject at hand, even given a decent background in the area. I know the
suggestion for the latter is often to spend time digging things out and then
trying things out to see what the result is, but there are people like me
who no matter how many things I can discover experimenting with code, still
feels lost if I do not have a clear understanding of the ideas and concepts
behind what I am doing.

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

You have "hit the nail on the head" so to speak. It is easy to know
something intimately, if one is the creator, and not realize that others do
not have an understanding which the creator does. OTOH I understand the
creator's reticence to slow down and explain things from a newbie's point of
view. Unfortunately that reticence has often led to some great programming
concepts going by the wayside because an audience finds it just too difficul
t to understand and therefore use.

>
> I believe it's important to have good documentation.

Bravo ! It is good to know there is someone else out there who believes
that. I will go even farther. I think good documentation in the programming
world is just as important as good implementation.

> I'll be glad to lend assistance to any updates, though my proofreading
> skills seem to be far better than my writing skills.

My writing and proofreading skills are both pretty good. I will also be glad
to lend assistance to anyone who asks me if I can help improve their Boost
documentation as long as I can understand what they are doing. I won't write
someone else's documentation for them in the sense that they don't feel that
they have time to work on it themselves, which is something I can
nevertheless personally understand as my own time, like most everyone
else's, is limited by the needs to work and make a living.