Re: Something off my chest about Boost

From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2019-07-17 11:05:14

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