Re: Something off my chest about Boost

From: pbristow_at_[hidden]
Date: 2019-07-17 08:34:00

> -----Original Message-----
> From: Boost <boost-bounces_at_[hidden]> On Behalf Of Maarten Verhage
> via Boost
> Sent: 16 July 2019 21:10
> To: Boost <boost_at_[hidden]>
> Cc: Maarten Verhage <m_r_verhage_at_[hidden]>
> 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/quic
> 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