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