Something off my chest about Boost

From: Maarten Verhage (m_r_verhage_at_[hidden])
Date: 2019-07-16 20:09:35

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

To make Boost more accessible to people I believe Boost should ask more on this from current and new library authors.

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.

Best regards,
Maarten Verhage