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

[Benjamin Root]

On Sat, Jul 3, 2010 at 9:03 PM, Bruce Southey <bsouthey at gmail.com> wrote:

> On Sat, Jul 3, 2010 at 11:34 AM, Ralf Gommers
> <ralf.gommers at googlemail.com> wrote:
> >
> >
> > 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.
>
> (Using the word 'diff' was perhaps too limiting - probably more like
> track changes in word processors is more appropriate terminology.)
> Thanks for pointing that out because I had to search a few examples to
> find an example. Otherwise all you get is a 'diff to svn'.
> An example is:
>
> http://docs.scipy.org/scipy/docs/scipy.stats.distributions.rv_continuous/log/
>
> Yet you can not tell what was changed and why beyond a trivial comment
> (that is often not very correct). There is no link to the discussion
> so you do not know what version the discussion applies to.
>
>
At that link, you can select two versions and see the difference between
those two revisions by clicking on the "Differences" button.  This is much
like viewing the history on wikipedia.  And, if you want to see what the
docs looked like for a particular version, you can  click on the date time
for that revision on the left

I hope this helps.

Ben Root
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100703/da3b31ce/attachment.html>