Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-10-10 22:10:38

Andrew Hundt wrote:
> I have to say Boost's documentation is generally excellent.

I would say that the quality of the boost documentation is all over the 
place.
I'm going to divide my observations into Reference Documentation
and Narative or Tutorial Documentation.

Reference Documentation.
=================

Excellent examples

Fusion
MPL
Iostreams

I'm sure there are others.  These pages have a regularity which which
suggests they can be filled in almost by "form filling" or by an
automatic tool such as DOxygen.  It looked to me that DOxygen
might be configured to do it but it looked like a lot of work.

Also these libraries share a strong, clear and formal set of
"Concepts" (Type contraints) in the SGI/C++ standard manner.
This makes the generation of good documentation more
automatic.  Also note that these examples include a small
example to show the function, class, or template is used.
This in theory is not strictly necessary, but very, very helpful
in practice.

These examples also share a clear classification of concepts,
classes, functions, macros, etc.

Bad Examples
=========

Units - no documented type requirements
Numeric Conversion - information might be in there - but
since it doesn't follow conventional layout I can't find it.

Everything else
==========
There are other good and bad examples and most
libraries follow between these two examples.  One big
problem is that the customary way of making reference
documentation for templates is only really well described
in the SGI website.  http://www.sgi.com/tech/stl/
The C++ standard has information on this - but as usual it's
border line unreadable.

Narative or Tutorial Documentation
========================

As has been mentioned, it's very difficult to prescribe what this aspect
of the documentation should contain due to the wide variety of scope, and
scale of the various libraries. Clearly something like spirit can't be 
expected
to teach the whole theory of parsing.  And something like BOOST_FOR_EACH
doesn't need much of an explanation at all.  Never the less...

Excellent examples.
=============
Spirit - an amazing tutorial on parsing.  One can actually enjoy reading 
this
even if you don't use the library.  Beautifully crafted graphics as well.

enable_if - a very weird and unintuitive concept pretty well explained.

Bad Examples
=========

Units - there are lot's of specific examples which are very helpful, but no 
"tutorial which
builds up from something simple. Certain important things like "system"
are barely touched upon.

Random - very well designed library (which I believe is now part of the
standard) but reading the documentation it took me forever to figure
out that there are really two more or less orthogonal pieces - generator
and "distributors" and what the role of each is.  I'm sure a better
tutorial would have helped.

Everything else
==========
of course everything else is somewhere in between.  This makes
very hard to make more general statements.

I used as examples only those libraries I've spend enough time with
to actually use in some other program so don't feel disappointed
(or relieved) if your library isn't mentioned above.  Also I don't
want talk about this or that libray - they are only examples for
the general discussion.

Summary
======
I've already pointed to my more extensive thoughts on the subject
and I don't want to test the indulgence of the viewers here with the
details.  I'll boil it down to a couple of points.

a) Make reference documentation which looks like that of the SGI
website. Write this while you're writing your library.
b) Write a couple of tutorial examples while your writing your library.
c) By the time you are ready to submit your library for review, you
should be able to write a short tutorial.  Take the view that you
need to "sell" the library.  Motivation and walk through of a simple
but useful example so the reader cat "get the idea" in 15 minutes.

Thanks for indulging me - I trying hard not to rant.

Robert Ramey