Re: [boost] Why is the boost documentation so bad?

Subject: Re: [boost] Why is the boost documentation so bad?
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-09-08 12:30:48

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-for-c-libraries-with-minimal-effort

See you there.

Robert Ramey