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

Bruce Southey bsouthey@gmail....
Sat Jul 3 11:13:29 CDT 2010


On Sat, Jul 3, 2010 at 10:31 AM, David Goldsmith
<d.l.goldsmith@gmail.com> wrote:
> On Sat, Jul 3, 2010 at 7:24 AM, Benjamin Root <ben.root@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.

>>
>> 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@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@sun.ac.za>:
>>> > On 2 July 2010 14:14, Joe Harrington <jh@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@scipy.org
>>> > http://mail.scipy.org/mailman/listinfo/scipy-dev
>>> >
>>> _______________________________________________
>>> SciPy-Dev mailing list
>>> SciPy-Dev@scipy.org
>>> http://mail.scipy.org/mailman/listinfo/scipy-dev
>>
>>
>> _______________________________________________
>> SciPy-Dev mailing list
>> SciPy-Dev@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@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>

Bruce


More information about the SciPy-Dev mailing list