[SciPy-Dev] SciPy docs: volunteers needed now!

[Ralf Gommers]

On Sun, Jul 4, 2010 at 12:13 AM, Bruce Southey <bsouthey at gmail.com> wrote:

> On Sat, Jul 3, 2010 at 10:31 AM, David Goldsmith
> <d.l.goldsmith at gmail.com> wrote:
> > On Sat, Jul 3, 2010 at 7:24 AM, Benjamin Root <ben.root at ou.edu> wrote:
> >>
> >> Joshua,
> >>
> >> In addition to the very technical writing for individual functions, we
> >> also need documentation that is accessible to newcomers.  Many modules
> do
> >> not implement any functions themselves, but act as a grouping module
> (for
> >> example, scipy.io).  These modules could definitely use good,
> up-to-date,
> >> summary narratives.  Even some modules further down the stack can still
> >> benefit from good summaries.
>
> What would really benefit is a solid example for different types.
> There are so many inconsistent styles in the numpy documentation - I
> know I wrote some. You can always see that when there are different
> definitions (when present) for input that are array-like. There should
> be one single definition for these common input and output that should
> be immutable by the writer and should automatically appear.
>

That would be nice but I don't see how that's technically feasible. To see
whether the input is ndarray or array_like you just have to look at the
code. And you'll always end up with some minor inconsistencies with many
writers, but that's what the review/proof stages are for.

>
> >>
> >> To everyone, if you do join the documentation efforts to contribute
> little
> >> bits of writing, it is a common courtesy to notify any others who might
> also
> >> be working on a particular document.  The current system does not
> >> automatically notify authors of any changes, so it is hard to know if
> any
> >> changes have been made.  General rule of thumb is to notify authors who
> have
> >> made changes to the doc within the last 3 months (I believe).
> >
> > Actually, all you have to do (have used in both senses of the word, i.e.,
> > are "required" to do and all that is necessary to do) is click on the log
> > link when viewing a docstring in the Wiki, note the person who worked on
> it
> > last, how long ago that was, and then as Ben says, if it was in the last
> > three months, give or take, contact them and ask them if it would be ok
> if
> > you worked on it.
>
> And where is the email or notification button? The more loops to jump
> through the less people will jump.
>

Good point.

>
> Where do you see the changes made? It should be a diff.
>

Under Log you have access to all diffs for a docstring.

>
> Why does the second person have greater authority to override the
> original author?
> Why should I have to go back and check that the later revisions are
> correct?
>
> If the first author brings a docstring to "needs review" status there's no
need for a second author to work on it. If it's still in "being written", it
wasn't finished in the first place. And later edits possibly overwriting
earlier ones is just the nature of wikis.


Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100704/3dd09445/attachment.html>