[AstroPy] Summer Doc Marathon status report and request for more writers

[Joe Harrington]

This is an interim status report on the Summer Documentation Marathon.
It is also an invitation and plea for all experienced users to
participate!  I am cross-posting in an effort to get broader
participation.  Please hold any discussion on the scipy-dev mailing
list.

As you know, our immediate goal is to produce first-draft docstrings
for the user-visible parts of Numpy in time for a release before Fall
classes (about 1 August).  The short version is: We are really moving
along!  But, we need *your* help to make it in time for August.

Here's the scoop:

1. We have all our infrastructure, standards, and procedure in place:
We have a wiki that makes editing the docs easy and even fun.  It
communicates directly with the numpy sources.  We have PDF and HTML
reference guides being generated essentially automatically:

http://sd-2116.dedibox.fr/pydocweb
http://mentat.za.net/numpy/refguide/NumPy.pdf
http://mentat.za.net/numpy/refguide/

The wiki front page contains or points to all you need to get started.

The wiki lets you pull down a docstring with a few mouse clicks, edit
on your machine, upload it, and see how it will look in its HTML
version right away.  You can also read everyone else's docstrings,
comment on them, see the status of the project, and so on.  The
formatted versions necessarily lag the docstrings on the wiki because
they are made whenever the docstrings are checked into the sources.

2. We have documented about 1/4 of numpy in a fairly professional way,
comparable to the reference pages of the major commercial packages.
The doc wiki is probably the next place to go if your question isn't
answered by the docstring in the current version's help(), since you
can look at the new docstrings we've generated, and they're *good*!

3. But, we're only 1/4 of the way there, we're halfway through the
summer, and some of the initial enthusiasm is waning.  The following
page tells the tale:

http://sd-2116.dedibox.fr/pydocweb/stats/

As you can see (you did click, right?  please click...), there are
2323 numpy objects with docstrings.  Of these, 1464 we deemed
"unimportant" (for now).  These are generally items not seen by
regular users.  This left 859 objects to document in this first pass.
We've done 24% of them at this writing.

Now, 24% is really exciting, and I'd like to take a moment to say a
public "Hooray!" for the team (no particular order):

Stéfan van der Walt	Pauli Virtanen 	
Robert Hetland		Gael Varoquaux 	
Scott Sinclair		Alan Jackson 	
Tim Cera		Johann Cohen-Tanugi
David Huard		Keith Goodman

Together these ten have written around 7500 words of documentation on
the community's behalf, mainly as volunteers.

HOWEVER, we can all do the math.  We've spent one of our two months.
We are 1/4 of the way there.  Progress is slowing, and even if it
didn't, we wouldn't make it in time.  This is not a sprint, it's a
MARATHON.

			WE NEED YOUR HELP!

And we need it now.  Are you excited by the idea of having
documentation for numpy by the Fall release?  Of having docs that
answer your questions, that have *good* examples, that really save you
time?  If so, then please invest just a fraction of the time that
documentation will save you in the next year alone by signing up on
the wiki and writing some.  If each experienced user wrote just a few
pages, we'd be done!

If you don't think you know enough to write, then do some reviewing.
Are the docs readable?  Do you understand the examples?  Each
docstring on the wiki has an easy comment box waiting for your
thoughts.

You will have a reference guide in the next release of numpy!  I hope
you will help make it a complete one.  Sign up on the doc wiki today:

		http://sd-2116.dedibox.fr/pydocweb/

Thanks,

--jh-- and the SciPy Doc Team

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 at physics.ucf.edu