[SciPy-dev] documentation - looking to hire

Joe Harrington jh@physics.ucf....
Fri Jan 25 23:20:16 CST 2008


I'd like to use Python to teach my astronomical data analysis class
next semester.  I tried using it last semester, and it was a big
problem because the students could not find docs for the routines.
They (and I, it was my first real use of Python) spent many hours at a
stretch looking for docs on basic routines that had little or no
docstrings.  Lots of other things were missing, too, like searchable
lists of routines, routines categorized by topic areas,
getting-started and user guides, etc.  Travis's book was too
high-level for this purpose; it's written for a different audience.

To use Python next semester, I'd need at least adequate docstrings for
all of numpy and certain parts of scipy, and for some of the
above-mentioned lists to be made, ideally automatically.

I'm looking for options to hire one or more people to do the job,
under some guidance from me and in concert with the community efforts.
This could be as a direct hire or on a subcontract to Enthought or
another institution.  I have not made any detailed plans for this, but
I'm guessing that one full time or two half-time people (a coder and a
writer) could do a good-enough first cut at the job, provided they
were already competent at numpy/scipy and were good writers.

If you are interested in taking on this work, from roughly now until
the end of the summer, please email me directly and let me know a bit
about yourself and your availability.  If you have ideas on how this
might be done to best integrate with the community effort, respond to
the list.  Your collective response will shape my thinking on how to
do this best, such as the level at which to hire.

If you look at http://scipy.org/Developer_Zone , you'll see that I've
written some basic description of the first two needs (which needs
editing, but it is late), but that I haven't identified a doc lead nor
a doc process.  It would be very helpful if someone could describe for
me what this process is.  Is it as simple as writing a docstring
according to

http://projects.scipy.org/scipy/numpy/browser/trunk/numpy/doc/HOWTO_DOCUMENT.txt
and
http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py

and entering it as a Trac ticket?  Is there any review?  How about
keywords for indexing?  What tools exist or are contemplated for
searching?  Is there any tool for extracting all the docstrings and
putting them out either as files or in one big file, for searching or
reading while not running python (or even being on the web)?

Thanks,

--jh--
Prof. Joseph Harrington
Department of Physics
MAP 414
4000 Central Florida Blvd.
University of Central Florida
Orlando, FL 32816-2385
(407) 823-3416 voice
(407) 823-5112 fax
(407) 823-2325 physics office
jh@physics.ucf.edu


More information about the Scipy-dev mailing list