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/