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

[David Goldsmith]

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

As far as informal style: yes, some doc is better than no doc, and reviewers
and/or users will eventually come along and say how they think it should be
improved - please don't let any insecurities be a deterrent: every version
is saved; worse comes to worse, someone comes along, doesn't like your
changes and reverts, but at least you tried and you can't "break" anything.
:-)

More later (but I like the dialogue that's started in my silence).

DG

>
> 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
>>
>
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>


-- 
Mathematician: noun, someone who disavows certainty when their uncertainty
set is non-empty, even if that set has measure zero.

Hope: noun, that delusive spirit which escaped Pandora's jar and, with her
lies, prevents mankind from committing a general suicide.  (As interpreted
by Robert Graves)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100703/84ad5626/attachment.html>