Re: Something off my chest about Boost

From: Robert Ramey (ramey_at_[hidden])
Date: 2019-07-17 16:28:53

On 7/16/19 1:09 PM, Maarten Verhage via Boost wrote:
> Dear Boost people,
> 
> Sorry but I need to get something off my chest regarding the Boost culture. To start of with something nice: I’m convinced Boost provides really useful facilities for C++ and some of them even make it into the standard C++ library. I do believe I can also contribute in a reasonable way. But the terse documentation keeps me from advancing. How it is currently stated on https://www.boost.org/users/faq.html
> 
> “What about documentation? A very simple library might be accepted with only a well commented header file. For more substantial libraries, some form of documentation is certainly going to be expected. HTML is the preferred form.”

That is clearly incorrect and the faq should be updated.  I don't think 
a library has ever been accepted without separate documentation.

> Speaking for myself. I think the first bits to get started with a library are on a sufficient level. You know the tutorial and the example code. But I get lost when I want to use the library for my own application domain. Then I do need library facilities not covered in the example code and sometimes the documentation mentions only the syntax. As I would imagine the library author working on his/her library judging whether to add a facility or not. Finally decided to add something: *the thought/motivation that goes along with that*, that would be so valuable for me to read that in the documentation!! Yes, I’m annoyed that I cannot read that in the documentation.
> 
> 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.

> Ok, a few examples for what I would like to ask the Boost community to demand from the library authors:
> 
> 1) In general, for the classes/functions where the user should directly deal with documentation like cppreference.com. So, with function prototypes showing the argument- and return types and a complete list of members along with what they do.
> 
> 2) Specifically for Spirit X3, a part on Parser Directives: https://www.boost.org/doc/libs/develop/libs/spirit/doc/x3/html/spirit_x3/quick_reference/directive.html
> I would very much like that the reason why each directive is added along with a minimal example that shows how to use just that directive.
> 
> Anyway, I hope people are also interested to discus documentation policies on this mailing list. I do believe it is important.

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