On Thu, Oct 10, 2013 at 6:01 PM, Niall Douglas
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.