Subject: Re: [boost] Improving Documentation
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2013-10-10 18:01:59
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.
ASIO is a good example of this: if you are familiar with reactor
style programming, ASIO is obvious and straightforward to use. If you
are not, its documentation apart from the tutorials is nearly
I've noticed the same thing with the math libraries, Boost.Spirit
etc. They all assume you already know their domain well, and all they
need to teach is how to get going with this particular variant.
I personally don't think that's a problem - if you need to learn how
to write a parser, I don't think anyone would claim you should start
that learning curve with Boost.Spirit. Same goes for ASIO, or AFIO
for that matter. Go learn the pattern elsewhere with a more forgiving
language and platform (e.g. Python), and return to the Boost
implementation when you really need a C++ implementation with all the
power, performance and caveats that brings.
Also, Stackoverflow is usually excellent on arcane Boost
documentation trouble spots. sehe on SO saved my bacon with
Boost.Spirit more than once.
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 .
: I say this as an author of two > 100,000 word books. The dollar
earnings per hour of effort is usually around minimum wage. It's
simply not rational to do usually when there are so many better
paying uses of your time.
-- Currently unemployed and looking for work. Work Portfolio: http://careers.stackoverflow.com/nialldouglas/
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk