On 9/8/17 12:26 AM, Gavin Lambert via Boost wrote:
On 8/09/2017 14:21, Florian Lindner wrote:
I really love to use boost libraries in my project, but I always wonder, for such an accomplished project, why is the documentation so bad?
In many cases, probably the same reason any other technical documentation is bad -- it is written by the original developer/maintainer, who has a mental model of how everything fits together and on occasion will omit things because they don't realise what sort of questions people will have or that what seems self-evident to them might not be to others.
This is basically the correct answer. It's not a Boost problem, it's a software development problem. As software gets more sophisticated, the problem becomes worse. In the past I've had a lot to say about this problem. I always carp about it in boost reviews and offer what I believe to be constructive suggestions. But still it's a problem. I've come to believe that I understand the source of this problem and what the route to the solution is. For those who might be interesting, I will be expounding on this subject at the upcoming CPPCon 2017: https://cppcon2017.sched.com/event/BgtD/how-to-write-effective-documentation... See you there. Robert Ramey