[Numpy-discussion] Documentation roles in the numpy/scipy documentation editor

Ralf Gommers ralf.gommers at googlemail.com
Mon May 7 16:14:56 EDT 2012

On Mon, May 7, 2012 at 7:37 PM, Tim Cera <tim at cerazone.net> wrote:

> I think we should change the roles established for the Numpy/Scipy
> documentation editors because they do not work as intended.
> For reference they are described here:
> http://docs.scipy.org/numpy/Front%20Page/
> Basically there aren't that many active people to support being split into
> the roles as described which has led to a backlog of 'Needs review'
> docstrings and only one  'Proofed' docstring.  I think that many of these
> docstrings are good enough, just that not enough people have put themselves
> out front as so knowledgeable about a certain topic to label docstrings as
> 'Reviewed' or 'Proofed'.
> You're right. I think at some point the goal shifted from getting
everything to "proofed" to getting everything to "needs review".

> Here are the current statistics for numpy docstrings:
> Current %Count Needs editing17 279 Being written / Changed4 62 Needs
> review76 1235 Needs review (revised)2 35 Needs work (reviewed)0 3Reviewed (needs proof)
> 0 0 Proofed0 1 Unimportant– 1793
> The "needs editing" category actually contains mostly docstrings that are
quite good, but were recently created and never edited in the doc wiki. The
% keeps on growing. Bumping all polynomial docstrings up to "needs review"
would be a good start here to make the % reflect the actual status.

> I have thought about some solutions in no particular order:
> * Get rid of the 'Reviewer' and 'Proofer' roles.
> * Assign all 'Editors', the 'Reviewer', and 'Proofer' privileges.
> * People start out as 'Editors', and then become 'Reviewers', and
> 'Proofers' based on some editing metric.
> For full disclosure, I would be generous with a 'Reviewed' label if given
> the authority because philosophically I think there should be a point where
> the docstring is 'Good enough' and it should be expected to have a life of
> continually small improvements rather that a point when it is 'Done'.

This makes sense to me.

> Regardless of what decision is made, the single 'Proofed' docstring should
> be available for editing.  I can't even find what it is.  I imagine that it
> should be on the docstring page at http://docs.scipy.org/numpy/docs/
> It used to be there - maybe the stats got confused.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20120507/4c07bd0f/attachment.html>

More information about the NumPy-Discussion mailing list