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

[Scott Sinclair]

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

I don't think we should remove the Scipy links from the front page,
that just makes point fixes less likely.

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

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.

Here is a first attempt at some milestones achievable in the short term:

1. All functions in the numpy toplevel namespace to be "ready for
review" or better.
    - There are many docstrings marked as "being written", which are
almost done and not being worked on.

2. Make sure that ndarray and all sub-classes (Matrix, MaskedArray,
recarray etc.) have docstrings at "ready for review" level or better.

Cheers,
Scott