Re: [boost] Improving Documentation

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

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 [1].

Niall

[1]: 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/