[SciPy-dev] Scipy Tutorial (and updating it)

[jh at physics.ucf.edu]

> 2008/12/5 Pauli Virtanen <pav at iki.fi>:

> I do not believe that preventing people from editing scipy docstrings
> will improve numpy documentation in any way; it will only prevent point
> fixes to Scipy docstrings (eg. people becoming annoyed with a specific
> bad docstring, and fixing it). We can say instead that "concentrate on
> Numpy", strongly, on the front page, and remove scipy links from the
> table on the front page.

This seems like a good compromise.  If we see a lot of migration to
systematic scipy writing (as opposed to point fixes), we can revisit.
I do want the developers to get in there and write in the areas where
they are expert, and to see point fixes made.

> What in my opinion could help Numpy documentation now is coordination.
> For example via milestones:
>
> - Compile a list of functions; sort it appropriately, and parcel it out
>  to manageable chunks (say, tens of items).
>
> - One possible way to parcel these could be to work in the order the
>  functions currently appear in the current reference guide.
>
> - I'd include a couple of "unimportant" functions to each milestone,
>  so that we don't end up with dull milestones at the end of the run.
>
> - Ask editors to work from top to bottom, one parcel at a time. Ditto for
>  reviewers.
>
> - I wouldn't necessarily include any deadlines, as these will slip,
>  which is demotivating.
>
> This should be fairly easy to compose, just requires putting up a new
> wiki page with appropriate links and sections for this. This could also
> speed up the review and QA that I feel is now not really progressing.

Do we have a coherent-enough group of writers to do this?  If so, I
think it's a fantastic idea.  What we said a few months ago was that
writers looking for something to do should take the Functional List of
Routines and write a section, or part of a section.  That would give
coherence to the text in each area, and encourage cross-referencing.

> "Scott Sinclair" <scott.sinclair.za at gmail.com> writes:

> I think that reviewing of docstrings is going to be tough to get going
> because it relies on the input of people who are already heavily
> involved in the project(s).  Any docstring that someone feels can be
> marked "ready for review" is usually pretty good anyway, we should aim
> to get as many docstrings as possible to this level before getting
> overly concerned about review.

We've already said that our current goal is to get all functions to
the state of "needs review" before pushing hard on the review, for the
reasons you state.  At this point, everything, finished or not, is
included in the numpy releases, as it is an improvement on the past.
Once everything "needs review", we push on the review, and when that's
complete, we only include changes that pass review.

We do have a few contributors who are mainly reviewers, and most of
the reviewed functions were approved by them, I think.

I have come to recognize two forms of review: content and
presentation.  Some functions that are clearly not well written and
others that are incomplete have been marked as reviewed.  My guess is
that a reviewer expert in the other area missed that the presentation
or content of the given item was lacking.  So, when we do get to the
point of review, I think we should consider requiring both kinds of
review.  It will slow us but will improve the product a lot.  Some of
our experts are not great writers and some of our great writers are
not experts.  This is hardly surprising, and both have a lot to
contribute, but we should ensure our liabilities get caught.

--jh--