Boost logo

Boost :

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


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk