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

[Benjamin Root]

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.

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

I really hope to see you all soon in the marathon!

Ben Root

On Sat, Jul 3, 2010 at 3:08 AM, Joshua Holbrook <josh.holbrook at gmail.com>wrote:

> My own reasons for hesitating have more to do with knowing that any
> documentation I write will likely have poor style. I tend to write in
> a very informal, conversational manner.
>
> That said, I'll try to do my part as I use parts of scipy, since
> having unprofessional documentation is probably better than having no
> documentation.
>
> --Josh
>
> 2010/7/3 Stéfan van der Walt <stefan at sun.ac.za>:
> > On 2 July 2010 14:14, Joe Harrington <jh at physics.ucf.edu> wrote:
> >>> I wonder whether there is any other approach that we can explore to
> >>> help generate more volunteer work?    Do you think it is mainly the
> >>> difference between scipy and numpy that explains the drop-off?   Or
> >>> something else?    To the extent that it is the technical differences
> >>> - do you think there would be any point in trying to establish
> >>> something like nominated experts or want-to-find-out type experts who
> >>> will offer to advise on particular parts of scipy - even if they don't
> >>> themselves write the docstrings?   Or anything else that might help?
> >>
> >> We already looked for topical experts.  We have a few; David can
> >> comment more.  In the end what we need are rank-and-file writers,
> >> people who will take something on, learn about it, and write about it.
> >> Yes, SciPy is more technical, but we've all dealt with harder tasks
> >> than documenting SciPy.
> >
> > All the posts I have seen talk about achieving higher word counts,
> > covering more functions, going bigger and better.  While that's
> > certainly what we want, such requests may be intimidating to new
> > contributors.
> >
> > My feeling is that we should identify a small handful of functions to
> > focus on.  That way, we may only document 10 functions a week, but at
> > least those will get done.  Emanuelle's suggestion to target specific
> > writers also seems sensible.
> >
> > Regards
> > Stéfan
> > _______________________________________________
> > SciPy-Dev mailing list
> > SciPy-Dev at scipy.org
> > http://mail.scipy.org/mailman/listinfo/scipy-dev
> >
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100703/5b46f543/attachment.html>