Re: Something off my chest about Boost

From: Hans Dembinski (hans.dembinski_at_[hidden])
Date: 2019-07-17 15:44:50

> On 19-07-17 10:33:10, Mathias Gaunard via Boost wrote:
>> On Tue, 16 Jul 2019 at 21:09, Maarten Verhage via Boost <boost_at_[hidden]> wrote:
>> 
>>> Another issue is when example code introduces three or more facilities at once.
>>> Then it is very hard for me to see how these bits relate to each other to make it useful for myself.
>> 
>> Personally I rarely even read textual documentation (examples,
>> tutorials...), it is usually more useful to just look at the reference
>> or the code itself (which should embed documentation in the form of
>> comments for the parts that matter).
>> Textual documentation is often glossing over some details which only
>> make sense if you already are familiar with how the library is
>> organized or showing trivial things that have little value.

I agree with Mateusz. I think the average user (including myself) wants to read a simple tutorial or getting started section first, which introduces the basic functionality of the library with a simple example/project. You first need to learn to walk before you can learn to run.

I personally find examples very helpful. In some cases, I learned more from reading the unit tests than from the docs, but that is not how it should work. The reference is very important, but there also has to be a user guide that explains some of the concepts and the structure of the library. How it all fits together. We want to empower the user to be creative with the library, not just follow recipes.