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

[Angus McMorland]

On 2 July 2010 15:46, Vincent Davis <vincent at vincentdavis.net> wrote:
> On Fri, Jul 2, 2010 at 1:28 PM, Emmanuelle Gouillart
> <emmanuelle.gouillart at normalesup.org> wrote:
>> I'm pretty sure that the observed lack of momentum is due to the
>> increased technicity of Scipy, as compared to Numpy.
>>
>> I myself feel that there is only a small fraction of Scipy docstrings I
>> could contribute to (that is, of course, docstrings of the functions that
>> I use). This is not quite true, because it's always possible to add
>> examples to a docstring even if one is not familiar with the function,
>> but we can't expect people to work on stuff they never use...
>
> There are actually a lot of functions that have very lacking docs and
> I think we should consider (and let it be known) small
> improvements/examples as being worth contributing and
> updating/commiting the docstrings with these small improvements.
> For example I am looking at stats._support  I am sure it is a seldom
> used corner of scipy but the docs are nearly non-existant.

This has basically already been said, but I'm going to put it in
slightly different words: there are currently 2610 entries in the
"Needs Editing" category on the docstring wiki. It seems, from a bit
of random clicking on function names, that many of these have _some_
documentation already, just not in the correct docstring standard
format. People with no more technical knowledge than a solid
understanding of the English language (sorry, all you other-language
speakers; care to start translation efforts?) could contribute greatly
by going through those docstrings and updating the 'Parameters' and
'Returns' sections to the correct format, and for bonus marks, by
adding an obvious example. Such information is, I would guess, the
most pressing need for people looking at docstrings for usage
information anyway. To summarize, the specialist knowledge barrier to
contribution is probably a lot lower than people might think.

Perhaps we should put the word out beyond scipy-dev, at least to
scipy-users, which may have more rank-and-file-worthy contributors.

Rank-and-file contributor,
Angus.
-- 
AJC McMorland
Post-doctoral research fellow
Neurobiology, University of Pittsburgh