Re: [boost] Something off my chest about Boost

On 19-07-17 10:33:10, Mathias Gaunard via Boost wrote:

On Tue, 16 Jul 2019 at 21:09, Maarten Verhage via Boost 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 sense a biased perspective of a Boost library author or a very advanced C++ user. I think majority of users of any advanced C++ library would not agree with you. Not long ago, I stumbled upon exchange of comments on StackOverflow about documentation of Boost.GIL users. It was not a bug report or a post to mailing list from an angry customer, but an honest comment about real user's experience. When I read those comments, I actually got excited that "Now I know what to fix in GIL docs first!", so I even archived it in GIL list [1] to remember what/where it was when I go for another round of GIL docs overhaul. [1] https://lists.boost.org/boost-gil/2019/06/0239.php Here are the comments copied: "Create an image of, say 512x512. Fill it with red pixels. Write to PNG. I can't find anything about doing any of that, at all, in the documentation for gil." "I had this same problem (...) the tutorial material shows you a ton of clever stuff with the view types...but then you come to try it yourself and realize you've still been given no idea how to actually create an concrete image for a view to refer to!" Having 10+ long experience with Boost, I think those comments apply to many of the Boost libraries. I think those also sun up well the issues that Maarten is describing here. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net Fingerprint=C081 EA1B 4AFB 7C19 38BA 9C88 928D 7C2A BB2A C1F2