[SciPy-dev] can I help with the docs?

[Gael Varoquaux]

On Tue, Aug 11, 2009 at 02:08:30PM -0600, Andrew Hawryluk wrote:
> Each year I train a new set of engineering internship students in our
> department, and one of the things they learn is Python.  Upon arriving
> here they have taken a single course on C++ and another on
> Matlab/Mathematica/Excel etc., but no Python.  I usually start them off
> reading "Dive Into Python", but I'd also like a single place to send
> them to get a brief tour of proper NumPy use.  The main NumPy & SciPy
> docs are excellent (and improving rapidly), but they start a bit too
> abruptly for my needs. For example, the NumPy User Guide currently start
> with installation instructions, and then the next page of body text is a
> table of all the available array types.

> I would like something that briefly explains what NumPy and SciPy are,
> and why/when arrays are better than lists/dicts, perhaps followed by a
> brief tour of some common NumPy tricks, before diving into the more
> detailed sections.

> One possible table of contents would be

> Introduction
>   What is NumPy?
>   Building/Installing
>   Short Tour
>   How to find documentation
> NumPy Basics
>   ...

> What direction were you thinking the User Guide would take?

Hey Andrew,

Good documentation, including documentation targetting newcomers, as you
point out, is paramount. I have also found that it is a tremendous amount
of work, because it requires reworking and revisiting the complete set of
available documentation all the time, to make sure that you have a
consistent set, that fits together in a narrative way, but also that
drive the reader to where he wants quickly.

I would very much like the numpy user guide, that you can edit on the
docwiki, to be that documentation. The reason being that it is a shared
project (it is easy for people to edit it), and thus it is easier to work
together and gather momentuml, that it is the 'official' documentation,
and thus will get more exposure, and that it is stored internally in a
format (sphinx) that makes it possible to produce an online doc as well
as a printed doc.

So I would say: just go ahead, and make your proposed changes in the
docwiki. They seem very sensible. If you have any problems, or want
review, ask on the mailing list. I say ask, I could say 'yell'. People
are all struggling with day-to-day life, deadlines, and many projects, so
you will probably not get as much review as you would like. However, in
my experience, such contributions grow the available material and end up
making it better all the time.

One thing that we have to be careful about, is not to repeat ourselves
too much in the documentation. If we do, the documentation can become a
huge maze that noones read. I believe the answer to this problem is to
cross link a lot, and to try to improve existing articles, when
available.

Thanks a lot for your interest,

Gaël