[SciPy-dev] 2-review system on doc wiki

[Bruce Southey]

On Sat, Feb 13, 2010 at 10:39 PM, David Goldsmith
<d.l.goldsmith at gmail.com> wrote:
> On Sat, Feb 13, 2010 at 5:22 PM, Bruce Southey <bsouthey at gmail.com> wrote:
>>
>> On Sat, Feb 13, 2010 at 12:30 PM, Joe Harrington <jh at physics.ucf.edu>
>> wrote:
>> > Chuck Harris recently posted on the numpy-discussion list a request
>> > for numpy 2.0 requirements.  I suggested that we include reviewed docs
>> > in 2.0.
>>
>> I think you need to a provide a plan on how this can be done although
>> clearly it will not be the 2.0 release but perhaps the somewhere in
>> the 2.x series.
>>
>> >
>> > The problem is that the docstring review is stuck.  We need to
>> > implement both a technical and a presentation review, but we currently
>> > lack labor to do the job.  Pauli Virtanen has been busy with other
>> > commitments, so there has been little progress on doc wiki changes.
>>
>> What do you actually need by technical review and presentation review?
>> I think that we need some sort of checklist that people can go through
>
> http://docs.scipy.org/numpy/Questions+Answers/#reviewer-guidelines
>
> First promulgated 2009-07-22, updated 2009-09-28, 2009-10-01
>
> Unfortunately, as I say there, asking for a precise "checklist" for the
> "presentation" review is _perhaps_ intractable (too much inherent
> subjectivity IMO), but I don't feel that should preclude it being done.
>
> DG

Never knew that existed because it is rather different from:
http://docs.scipy.org/numpy/Front%20Page/#roles-reviewing

But my question is what is 'technical review' and what is 'presentation review'?
Without clarifying those any steps are rather pointless. From the page
you linked, these two things are combined. Questions like 'is it
clear?' and 'is it helpful?' is not what I would call presentation but
technical.

To me, presentation review should only address if it meets the
docstring standard
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard)
and is displayed correctly.


I just think that the 'bar' here is set too high for a volunteer
project. Also I think that this 'new version' is asking too much
especially when people have been working under a rather different
approach. Also there is no conflict resolution between all the steps
involved.



Bruce