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

Tim Cera tim at cerazone.net
Mon May 7 13:37:10 EDT 2012


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'.

Here are the current statistics for numpy docstrings:
Current%CountNeeds editing17279Being written / Changed462Needs
review761235Needs
review (revised)235Needs work (reviewed)03Reviewed (needs proof)00Proofed01
Unimportant–1793


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'.

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/

Kindest regards,
Tim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20120507/1689545e/attachment.html>


More information about the NumPy-Discussion mailing list