Op 16-07-19 om 22:09 schreef Maarten Verhage via Boost:

Anyway, I hope people are also interested to discus documentation policies on this mailing list. I do believe it is important.

Just discussing doesn't make things better though. I'd suggest pointed suggestions for improvements. Many library maintainers would be happy to incorporate feedback.And especially if you can provide a pull request that does some of the work (e.g. removing tangential stuff from examples). Everything here is the work of volunteers. Documentation is vetted very rigorously before libraries are accepted, but documentation has wildly different roles for different audiences. There's a lot of value in complementing the developer vetting with end-user feedback. Just my $0.02 Seth

Hi Maarten - On 7/16/19 13:09, 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.”

I'll fix this... because there is no library that is going to be accepted today that has only a well commented header file. There are other parts of the FAQ that are crusty and need some revising. <snip some good examples>

Anyway, I hope people are also interested to discus documentation policies on this mailing list. I do believe it is important.

I hope you get involved in helping the community make a better thing! Documentation becomes particularly hard when you are close to the problem. The user that is first picking up a library is often the best to provide feedback and later even revisions to documentation to make it better. Also, not all library authors are awesome documentation writers. We all have different skills. I think you will find that authors would be thrilled to have input on documentation and especially pull-requests with updates and changes. I know that the Spirit author wouldn't mind having concrete suggestions for improvements. I appreciate your feedback. Stay around and help us. We are all volunteers wanting to build something better! -- Michael Caisse Ciere Consulting ciere.com

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

On Tue, 16 Jul 2019 at 21:09, Maarten Verhage via Boost wrote:

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.

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.

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

The main problem with the Spirit documentation is that it has tutorials and a reference of the different parser operators, but there is no real reference documentation of the functions and other software infrastructure that actually drive the work and the requirements their inputs must satisfy. So you have to infer that from tutorials or just look at the source code. This is a common problem with a lot of Boost libraries. Anyway, for your problem, your confusion might come from the fact that you don't realize that parsing with Spirit combines an attribute parser and a skip parser, that the skip parser is called before and after each call to the attribute parser, and that parsing yields the attribute. Those directives you linked to simply allow you to change how those are called or what result they yield within a localized context. There indeed doesn't appear to be any documentation on this. Now a simple idea one might implement to improve the quality of boost documentation is simply mandate reference documentation in the form of a list of public header files with the public functions they declare together with their signature. That sort of thing is easily generated by Doxygen and it is already well integrated into the Boostbook toolchain.

On 16. Jul 2019, at 22:09, Maarten Verhage via Boost wrote:

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

Boost.Histogram was added just recently, and the documentation was thoroughly checked in the review when I submitted it. Documentation is essential for the reviewers, too, because they usually look at the library for the first time and need to figure out how to use it based on the documentation (or by looking into the code, but if you need to look into the code to figure things out, the documentation has failed already). It is difficult to compare docs and source code, but the Boost.Histogram docs have 19023 words, and the source code has 28844 "words". Roughly, the docs make up 40 % of the library, and that although Boost.Histogram is a "simple" library with a narrow application domain (not so narrow when you look more closely, because of how general it is). As other have said, it is generally a good idea to write an issue for the particular library in question and - even better - submit a pull request. Github makes contributing easier than ever before. Best regards, Hans