Re: Something off my chest about Boost

From: Michael Caisse (mcaisse-lists_at_[hidden])
Date: 2019-07-16 23:26:32

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