Re: [boost] AFIO on the Incubator

Subject: Re: [boost] AFIO on the Incubator
From: Robert Ramey (ramey_at_[hidden])
Date: 2015-08-19 11:22:44

On 8/19/15 2:49 AM, Niall Douglas wrote:
> On 17 Aug 2015 at 14:58, Robert Ramey wrote:
>
>>> FYI I know of about seven people who have ever even tried AFIO in 30
>>> months. It's too niche, though when you see my brand new workshop
>>> tutorial with benchmarks on Friday I think that might radically
>>> change :).
>>
>> Maybe a year ago I went though the documentation of AFIO and wrote a
>> comment based on that experience.  I've seen that the package has
>> improved enormously since then. I like to think that my comment made a
>> small difference. (Incidently, I removed my old comment because I didn't
>> think it was relevant any more.)
>
> Your comment made more than a small difference in fact. It made me
> realise I'd need to implement a much more friendly user facing API.
> You are the Boost.Serialisation guy after all, if you're not lighting
> up with excitement then I'm doing something very wrong.

This is gratifying to me.

> I still don't have iostream serialisation support in AFIO, nor do I
> wish to add it (it's racy). However I have thrown serialisation folk
> a bone by making the new workshop tutorial iostreams based, so I show
> how to adapt AFIO to iostreams in a race free way.

serialization is orthogonal to iostreams so I don't know if that's 
relevant.

I would expect that some sort of support for iostreams would be almost a 
requirement.

>>   I think I'm starting to get an idea of
>> what problem the thing is supposed to address.
>
> I'm hoping by the end of the new tutorial anyone reading will be
> convinced. I hope.
>
> We'll find out on Friday. I have the final step in the tutorial to
> finish before then, but otherwise it's ready.

TL;DR

I very much want you (and others of course as well) to be successful in 
your quest to get your library added to Boost.  I believe that the http 
experience shows the wrong way to go about it.  My personal experience 
with the serialization library was a tortured affair involving an 
initial rejection illustrates the promise and power of the Boost library 
review process.  It was personally devastating to me to fail at this 
endeavor - but the rejection was correct as the first version of the 
library wasn't good enough.  It's only due to a particular personality 
defect (pathological stubbornness) which resulted in me redoing the 
whole thing while incorporating all the feed back from the review.  The 
rest is history - the library was accepted and eventually came to be 
probably one of the most commonly used boost libraries.

Here is my advice - Do not do this.  Get it right the first time.

In order to spare others the disappointment, frustration, and huge 
amount of extra work, I was motivated to create the Boost library 
incubator.  I've tried to summarize my experience in such a way as to 
help library authors be more successful.  It's very hard to know whether 
or not it has been successful - the user feedback part has been a 
disappointment but its in large part done so we'll see.

Here is my meta advice - Follow my advice at www.blincubator.com.  It's 
meant to be almost a "form filling" exercise to create a boost quality 
library that will be accepted.

In particular,

a) spend more time and attention writing the documentation
b) follow the documentation guidelines
c) write, document and implement concepts
d) write the documentation, code, and tests together

There are two (at least) ways of thinking about creating a software library.

a) It's a sub machine - like a starter motor for a car which can be 
included in any other car design.

b) it's a mathematical proof.  Given conditions a, b, c it will produce 
results x, y and z.

The latter train of thought is more likely to be successful.  This also 
casts a library as just an implementation of the ideas expressed in the 
documentation.  As extraneous ideas are cast from the "proof" the 
library get's smaller - and paradoxically more useful.  Less a bag of 
disparate features and more the manifestation of a clearly defined 
concept which can more easily composed.

READ

In particular, I do not want to see you (in particular) fail in this 
endeavor.  To this end I will commit myself to reviewing and/or 
commenting on your library as soon as you tell me that you've made the 
changes you want to include and think it's ready.  Hopefully, you'll 
find this useful in preparing for the review.  You may or may not 
incorporate my observations, but at least you won't be caught with your 
pants down when it comes time for the review.

Robert Ramey