Re: [boost] Something off my chest about Boost

-----Original Message----- From: Boost On Behalf Of Maarten Verhage via Boost Sent: 16 July 2019 21:10 To: Boost Cc: Maarten Verhage Subject: [boost] Something off my chest about Boost

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/qui... k_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.

You are absolutely right about the importance of documentation, including worked examples. But sadly, it is both hard, harder than you might think, and hard time-consuming work too. The tools to do this are a not easy to use and tools that work for small libraries don't work when scaled up for big libraries (like Boost.Math). The sad truth is that most authors are so exhausted by getting through the hoops and over the hurdles of the code review process, that they often don't have the enthusiasm and strength to give as much attention to the documentation. Offering to help the author/maintainer with documentation for a particular library is probably the best thing you can do? Asking questions (even if dumb) like "what is the function and usage of this feature?" and capturing the answer is valuable. HTH Paul Paul A. Bristow Prizet Farmhouse Kendal, Cumbria LA8 8AB UK