[SciPy-dev] Summer Doc Marathon status report and request for more writers

[Alan Jackson]

Let me add to the plea. I'm not actually *that* experienced a user - at
least with numpy and python. But I can learn enough to write
documentation, and it is forcing me to improve my numpy skills and
knowledge, as well as deepening my knowledge of statistics (I've been
working on the distributions). My point is this - you don't have to be
an expert - you just have to be willing to expend some effort learning
enough to write a document. And that effort will pay dividends - the
best way to learn something is to teach or document it.

Working on one of the docstrings already gave me an idea for a research
project!

On Thu, 03 Jul 2008 17:59:08 -0400
Joe Harrington <jh at physics.ucf.edu> wrote:

> 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
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://projects.scipy.org/mailman/listinfo/scipy-dev


-- 
-----------------------------------------------------------------------
| Alan K. Jackson            | To see a World in a Grain of Sand      |
| alan at ajackson.org          | And a Heaven in a Wild Flower,         |
| www.ajackson.org           | Hold Infinity in the palm of your hand |
| Houston, Texas             | And Eternity in an hour. - Blake       |
-----------------------------------------------------------------------