Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Andrew Hundt (athundt_at_[hidden])
Date: 2013-10-10 18:47:03

On Thu, Oct 10, 2013 at 6:01 PM, Niall Douglas <s_sourceforge_at_[hidden]>wrote:

> On 10 Oct 2013 at 15:00, Andrew Hundt wrote:
>
> > So, is there anything we can do about it?
> >
> > I remember a couple of years ago Boost had a "Bug Sprint" with the goal
> of
> > closing lots of open tickets. Perhaps we should do a "documentation
> sprint"?
>
> Historically Boost's libraries were sorta seen as proto-standard
> libraries, so their documentation was written in the style of the ISO
> C++ standard i.e. it assumes you already understand the patterns used
> in the library, and all you need is the "how to use" detail.
>

I completely agree that boost docs should generally be a "how to use"
guide. The additional steps I also think would be reasonable are for the
"how to use" detail to be easier to browse around and links to all the
existing examples and tests.

Something that would truly be great would be for each function to be called
in some example. I believe there are many that are simply not covered.
Admittedly that would be a fairly lofty goal.

Links to a couple of resources to get started also couldn't hurt and
wouldn't be too difficult to add. For instance,
http://en.highscore.de/cpp/boost/introduction.html is not a bad
introduction.

Also, Stackoverflow is usually excellent on arcane Boost
> documentation trouble spots. sehe on SO saved my bacon with
> Boost.Spirit more than once.
>

Yes, I use stackoverflow for that purpose quite frequently!

>
> No one is claiming that Boost's documentation can't be vastly
> improved. But I think you'd find it starts bleeding into essays on
> theory, and an author could put that into a book which they could
> sell rather than giving it away. Or indeed provide training and
> consulting. Or anything else involving making money to pay for the
> time involving in writing additional docs, an endeavour which is
> certainly not rewarding [1].
>

I hope most authors aren't contributing to boost then deliberately skimping
on documentation to maximize the consulting fees. While I'm all for
consulting fees, that particular strategy doesn't seem to be in the general
spirt of Boost. :-) Admittedly, I'm having a tough time finding another
example of a highly renowned library with very solid documentation after I
exclude those with at least one company providing major backing for it.

I have to say Boost's documentation is generally excellent. However, a few
things could be reorganized to make it less confusing which could really
lower the barrier to entry for newcomers.