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

Subject: Re: [boost] Why is the boost documentation so bad?
From: Gavin Lambert (gavinl_at_[hidden])
Date: 2017-09-08 07:26:15

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.

I'm sure pull requests with suggested improvements would be welcomed.

> I want to get familiar with 
> http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/. What do I
> need to include? Neiter the tutorial, the reference or the usage 
> guidelines mention a #include line. This is something which stroke
> me quite often at various boost libs.
This is one of the older libraries in Boost, which might be a factor.

Most Boost libraries provide a single "master" header file which you can 
include to get all components of the library, and this is the typical 
usage when getting started.  You might later narrow to a subset once you 
know exactly which parts you want to use -- and generally your IDE can 
then help you locate which specific subfiles they're in.

Unfortunately different Boost libraries have different conventions for 
the name of this master header file, but generally one of the following 
will do the trick:

   * <boost/lib_name.hpp>
   * <boost/lib_name/lib_name.hpp>
   * <boost/lib_name/all.hpp>