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

On 4/3/16 9:56 AM, P F wrote:

...

On Apr 3, 2016, at 11:19 AM, Robert Ramey 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