[SciPy-dev] a doc challenge to all numpy/scipy developers

Joe Harrington jh@physics.ucf....
Mon Aug 4 16:51:03 CDT 2008


In the early days of the current numpy, urgency to get a working code
was so high that docs were largely set aside, save for Travis's book.
The doc project is now producing the API and user documentation that
has been missing from numpy, and will then turn its attention to
scipy.  However, new code is still being added to both projects,
sometimes without real docs.

I would like to ask all developers - even to challenge them - from
this point forward to accept only fully documented software into numpy
and scipy.  We are no longer in an urgent condition, and writing docs
is generally considered an integral part of development.

In my heart I'd like to issue the same challenge for patches as well.
If you know enough about a function to patch it, you can document it,
if it isn't already.  It doesn't take long.  Of course, I don't want
to encourage the perpetuation of bugs by placing a barrier to fixing
them, so I won't argue this point insistently.  At the same time, I
would argue that the lack of a decent docstring is a bug, and a
serious one.  So, please at least consider writing a docstring if you
write a patch to an undocumented function, particularly if you are
already writing docs and can knock off a good docstring in a short
time.

Thanks,

--jh--


More information about the Scipy-dev mailing list