Another example which just occured to me: http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/doc/ptr_inserter.htm... tells me how to copy elements, but I got to grep the source code to find out I need to include #include to get the back_inserter. Documentation was not helpful there. Am 08.09.2017 um 10:21 schrieb Florian Lindner:

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.

Best, Florian

On Thu, Sep 7, 2017 at 7:21 PM, Florian Lindner via Boost wrote:

why is the documentation so bad?

I think it is unfair to say that every library has bad documentation. I would like your opinion, what do you think of these docs? http://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/ref/boost__b... I realize that quality may vary from library to library. Perhaps you can open an issue for your specific documentation problem against that particular library? Thanks

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: * * *

Den 08-09-2017 kl. 04:21 skrev Florian Lindner via Boost:

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.

While it would help to have the docs upgraded/improved the front page has a link to a section called "library headers": http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/doc/headers.html Boris Schäling has an awesome online book: https://theboostcpplibraries.com/ full of nice examples. kind regards Thorsten

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