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

Subject: Re: [boost] Why is the boost documentation so bad?
From: Edward Diener (eldiener_at_[hidden])
Date: 2017-09-08 18:54:09

On 9/7/2017 10:21 PM, Florian Lindner via Boost wrote:
> Hello,
> 
> 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?
> 
> A few examples:
> 
> 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.
> 
> Also with the ptr_container lib, I want to find the refrence for the ptr_vector::insert function. I got to scan the
> reference pages of all members of it's class hierarchy to find the insert() function (it's in ptr_sequence_adapter).
> 
> References and example code often have no syntax highlightning and no linking and it's extremely hard to find
> documentation for a specific symbol, or from there, to jump to the source code.
> 
> I would really like to have a more uniform and a documentation that not feels like a annotated source code dump.
> 
> I use doxygen for my own projects and I know it can generate nicely looking, with syntax highlightning and linked
> documentation.
> 
> Please, don't take this offensive, it's just some feedback I wanted to give a long time.

Feel free to open an issue for any library's documentation you feel 
inadequate.

I completely agree with you that every library needs to specify these 3 
things near the beginning of the docs:

1) Level of c++ supported if it is anything above c++03.
2) Header files needed
3) Namespaces used

with optionally:

4) Build instructions for non header-only libraries

Furthermore I believe that some Boost documentation suffers from the 
syndrome that library authors believe that adequate docs mean 
examples/tutorial + reference, without having to provide any general 
explanation and discussion of the actual concepts of the library. But 
obviously most Boost libraries are first rate in explaining themselves 
and it is very hard to change the mindset of those few library authors 
who do not want to explain their libraries in a more expansive manner.

> 
> Best,
> Florian