Re: [boost] Boost.Fit review Mars 3-20 result

Subject: Re: [boost] Boost.Fit review Mars 3-20 result
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-04-03 14:34:20

On 4/3/16 9:56 AM, P F wrote:
>
>> On Apr 3, 2016, at 11:19 AM, Robert Ramey <ramey_at_[hidden]> wrote:
>>
>> On 4/3/16 7:36 AM, Vicente J. Botet Escriba wrote:
>>> The review of the proposed Boost.Fit library ended on Mars 20, 2016. The
>>> verdict is:
>>>
>>>    Conditional acceptance (a new review is needed)
>>>
>>
>> snip ...
>>
>> The about could be more accurately and succinctly stated:
>>
>> That is the library is rejected.
>>
>> The effort is not without merit and the author is encouraged to address the concerns raised by the reviewers and re submit the library.
>>
>>
>> I followed comments on the review fairly closely.  I think that submitters could improve their chances of success by doing somethings differently. I've always been forth coming on giving advice to these authors.  Of course, unsolicited advice isn't generally effective, but its good therapy for those that offer it.  In that vain I offer the youtube video of my presentation at CppCon 2014 "How you can make a Boost C++ Library".  I was sort of stunned by the lack of interest - only 14 attendees and pretty disappointed by the reception - about average according to statistics.  Oh well, one keeps trying.
>
> What are you suggesting I should’ve done differently?

My views on the subject can be found on the boost library incubator. 
These are in large part reflected in the youtube video cited. The 
suggestions are pretty mundane but I think they add up to alot.  You can 
find them there.  But off the top of my head I can cite a few of them.

Observations and assumptions:

a) most C++ library documentation is much worse than it should be.
This makes the library harder to use than it should be.

b) Unhelpful documentation is often a reflection that the library itself 
lacks clear focus on its goals and purpose.  The description of its 
implementation and usage ends up confusing and irregular.

c) The usual sequence of events is to write all the code and maybe the 
tests and then write the documentation as afterwards.  But in writing 
the documentation often reveals problems in the library itself - often 
times in a fundamental way. Now the author faces a dilemma: Does he move 
forward - take the library as a given and somehow patch together the 
documentation?  or does he go back and adjust the library to make it 
simpler or more regular.  If he does the latter, there is a huge danger 
that it's like pulling a thread from a sweater and everything ends up 
changing - then the documentation has to be done almost from scratch - 
again!  Since he already spent 10 times the time orginally anticipated 
he just wraps it up.

In the references cite above I have few concrete suggestions.

a) Follow the original SGI documentation as a model for reference 
documentation.  This is the first and best examples of how Type 
Requirements (aka concepts) drive the design of the library

b) At some point near the beginning write the introduction to the 
documentation.  This will require one to make a concise statement as to 
what problem the library is meant to solve and how it goes about doing 
it.  This is generally only a paragraph or two so it should be easy.

c) when you make a piece of code, make an example which demonstrates how 
to use it. When you think the example illustrates how the library is to 
be used and what problem it solves, then create a narrative page to 
explain this.

d) make the reference part of the documentation for a type/class soon 
after you make the code and test.  This will include the type 
requirements as well as reference on particular classes which model the 
type requirements.

e) When you make a critical design trade-off, add a paragraph to the 
"rationale" section so you don't forget.

f) Display and check the documentation as you go so you can verify that 
it reflects the reality of the code.

g) by the time you think your code is "done" you should now have most of 
the documentation done.  It's not a tedious chore that you had to do, 
it's part of the library development process.  And you've made the 
process of development easier because there is less going back and 
redoing previous work.  Of course there is still some of that, but it's 
less than it is if you wait until the end.  It's less work and the work 
is less tedious.

h) Now you think your "done" but before getting a formal review, try to 
rope someone into trying the library out from the documentation.  Every 
time your "guinea pig" has to ask you a question, it's an opportunity to 
update your documentation so that that question never will be asked 
again. Or if it does you can just respond with "look at page 999 of the 
documentation" I realize that that getting such a "guinea pig" is not 
easy.  It's one of the things I've tried to facilitate via the boost 
library incubator - with very little success.   Actually, every time 
from now into the future, every time someone asks a question with a trac 
item or posting to the list should result in small enhancement to the 
documentation so that that question doesn't come up again. In this way 
you're constantly moving forward.

So those are my concrete suggestions.

I realize that C++ programmer thinks that this is a trivial task and the 
he knows how to do it.  I also that I'm asking C++ programmers to 
respect my authority in this subject and this is a very large and bitter 
pill to swallow for those of use with large egos (which is basically all 
of us).  All can say is:

a) as the author of a very large and very complex library, the above has 
worked for me.

b) just be willing to give it a try.  It won't be any more unpleasant 
than what you're doing now and it just might work.

Robert Ramey