Re: [boost] Re: string algorithms review

From: Rob Stewart (stewart_at_[hidden])
Date: 2003-10-27 10:33:06

From: Beman Dawes <bdawes_at_[hidden]>
> At 04:38 AM 10/24/2003, Paul A. Bristow wrote:
> 
>  >PS I feel this long dialog may be showing a weakness in the review
>  >process.
>  >I can (from experience) understand authors' reluctance to put a lot of 
> work
>  >into the documentation (or redoing code) unless one can be sure that the
>  >code is going to be accepted.  Do we need to accept a proposal in
>  >principle, then have a
>  >revision period, and then finally review and accept as 'official' release
>  >version (1st version anyway)?
> 
> There is definitely a chicken-and-egg problem. Reviewers often want fairly 
> finished docs, but developers don't want to put effort into finished docs 
> unless a library is going to be accepted.

Paul's question wasn't just about documentation.  Can a proposed
library, with some minimally sufficient documentation and
framework sketch, be provisionally accepted before an author
begins rigorously pursuiing the idea?  That seems more than
reasonable.  There was much discussion regarding the efficacy of
a Boost PBSP well in advance of most of the work done on it.
That discussion gave credence to the idea before the hard work
began.

Sure, folks post queries as to whether there is interest in this
or that library, but that doesn't have the same visibility as a
formal proposal review, so fewer will seriously consider the
proposal's value.

Obviously, should a good idea prove unworkable, or should the
design deviate too much from the proposal, then the library can
still be rejected under this approach.  IOW, provisional
acceptance of a library does not guarantee final acceptance.

Even if those changes aren't adopted anytime soon, may I suggest
that documentation for an initial review not be part of the
review.  That is, documentation is required -- otherwise, many
will be unwilling to do the review -- but no requirements need be
levied on the documentation short of clarity and sufficiency.
The documentaiton should allow reviewers who have not previously
seen the library under review to understand its purpose, goals,
design notions, and contents.  Any questions raised during the
review should be noted as indications of material needed in the
final documentation.

By removing the rigor and formatting demands from the
documentation, the library author can worry about the details of
the code before its acceptance.  Then, once the library has been
(provisionally) accepted, the documentation must pass muster
during a follow-on review before full acceptance into Boost.

The drawback to this approach is that reviewers must come back to
participate in the documentation review and that those reviewers
will already have become familiar with the library.  The former
should not be too burdensome as they need to spend that time
either way if they provide a full review.  The latter means that
no retruning reviewers will approach the documentation as a
newbie to the library, so it may not get reviewed from the same
perspective.  Mitigating that, newbies will come along with
problems based upon deficiencies in the documentation, so it can
be corrected over time.

-- 
Rob Stewart                           stewart_at_[hidden]
Software Engineer                     http://www.sig.com
Susquehanna International Group, LLP  using std::disclaimer;