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

[Andrew Straw]

One thing I notice about the organization of the doc site that seems
sub-optimal is that functions are resolved to the module where they're
defined rather than their canonical namespace. In particular, clicking
on the page for array() from the main numpy page gives me a page with
the primary header saying "numpy.core.multiarray.array". I think that's
confusing, particularly to new users. All the more so since I believe
the "numpy.core" namespace is more-or-less for internal implementation
and it is discouraged to write external code referencing into numpy.core.

OK, I'll shut up now until I actually do some writing or editing on the
doc strings.

-Andrew

Joe Harrington 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
>