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 [EMAIL PROTECTED] _______________________________________________ Numpy-discussion mailing list [email protected] http://projects.scipy.org/mailman/listinfo/numpy-discussion
