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

Sat Jul 3 12:51:53 EDT 2010

On Sat, Jul 3, 2010 at 10: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.

I have just started making a long list of doc examples. This page
http://docs.scipy.org/numpy/Questions+Answers/
Is a great place to get started but if all you (I) want is a cheat
sheet with a fairly long list of style examples for each section and
the order the sections should be in. And this without all the noise
from the discussions related to the style. This was also going to
serve as a rst guide.
If others are interested in this we should probably add a wiki page for this.

Vincent

>
>>>
>>> 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.
>
> Where do you see the changes made? It should be a diff.
>
> 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?
>
>
>>
>> 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
>
> No bad documentation is worthless because either someone does not
> revisit because they assume it is done or think that the other person
> knows more so they don't touch it.
>
>>>
>>> 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.
>
> Just read a few of the numpy ones like cumsum and similar. Then just
> copy that style.
>
>>>>
>>>> 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.
>
> Just follow a good docstring from  a similar type of function. But
> also add a variety of examples that show the usage especially 2-d
> cases and weird cases as these also can act for doctests.
>
>>>>
>>>> --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)
>>
>> _______________________________________________
>> SciPy-Dev mailing list
>> SciPy-Dev at scipy.org
>> http://mail.scipy.org/mailman/listinfo/scipy-dev
>>
>>
>
> Bruce
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>