Re: Something off my chest about Boost

From: Maarten Verhage (m_r_verhage_at_[hidden])
Date: 2019-07-17 17:47:43

> I have had much to say regarding documentation of C++ libraries. see 
> https://www.youtube.com/watch?v=YxmdCxX9dMk&t=2s . I won't repeat here the 
> advice/observations contained in the video. I've also been a persistent 
> nagger and critic of the documentation of C++ libraries submitted to 
> review.
>
> I may be deluding myself (happens a lot!) but I honestly believe that 
> things have improved a significantly. Documentation for libraries recently 
> submitted for review have quite good documentation in my opinion.  Ones 
> that occur to me are histogram, out_ptr, mp11, leaf and others.  I still 
> have some specific complaints on these, but on the whole I believe that 
> things are much better than they used to be and generally far superior to 
> documentation of other C++ development projects.
>
> I get your complaint about spirit - beautifully prepared documents which 
> reflect a lot of effort.  But still seems harder than it should be. Would 
> be interesting to investigate this in light of more recent efforts to 
> determine why this is so.
>
> I appreciate you're bringing this up.  Such observations/complaints are 
> very useful.  But to make a difference might require investment of some 
> more effort. For example, it would be interesting to look at a few more 
> libraries and list your top/bottom ten.  I would guess that the bottom 
> would contain more older libraries.  I appreciate that this would be 
> significant effort so I'm not actually asking you to do this.
>
> Robert Ramey

Thank you all for sharing your thoughts about documentation. I admit I've 
not much
experience with other libraries. Good to hear that more recent library docs 
are considered
better.

I have sent a private email to Michael Caisse and Joel de Guzman (X3 author) 
for what I
think are improvements for the documentation.

> Hans Dembinski
> 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.

I agree with this. For Spirit X3 I do consider the examples in the tutorial 
too much
applications already. While my "toolbox" of parser programming facilities 
isn't
sufficiently filled.

With the inviting words from Michael Caisse it seems they are now willing to 
hear
feedback on documentation of Spirit X3. In my first email to them I can only 
share
my perspective that would do it for me. Maybe there are more users and 
past-users
(who have seen value in Spirit but considered it too hard to get along) who 
can give
constructive suggestions about documentation. Also I can share that email of 
today
to see if most people agree with this or just something to provide 
associations for
what they consider harder than necessary. But I don't know if that is 
appreciated.

Best regards,
Maarten Verhage