[SciPy-dev] Scipy Tutorial (and updating it)

jh@physics.uc... jh@physics.uc...
Fri Dec 5 12:10:46 CST 2008


Gael, what you describe below is just a collection of documents about
each of scipy's modules, written by the maintainers of those modules.
That is valuable to have, but it is not a user guide.  If you look at
the User Guide for any of our competing environments (IDL, Matlab,
Mathematica, etc.), or indeed for any large software package, you'll
find a document that is integrated across the areas of functionality.
It is oriented toward tasks the user wants to do, not necessarily the
structure of the software.  The "User Guide" name should be reserved
for a document that is planned from the start to Guide the User in
tasks of great interest to most users.  What you describe is one step
up from reference documentation, and it is useful to have, but it is
not integrative.

--jh--

Date: Fri, 5 Dec 2008 07:09:27 +0100
From: Gael Varoquaux <gael.varoquaux@normalesup.org>
To: jh@physics.ucf.edu, SciPy Developers List <scipy-dev@scipy.org>
Subject: Re:  [SciPy-dev] Scipy Tutorial (and updating it)
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
In-Reply-To: <wl8skp3qv4n.fsf@glup.physics.ucf.edu>

On Thu, Dec 04, 2008 at 08:16:24PM -0500, jh@physics.ucf.edu wrote:
> To expand (only a little, I promise!) on the User Guide, it needs
> chapters on specific numpy topics, starting with the text in the new
> numpy.doc module, and it needs chapters on general topics like
> plotting, 3D visualization, handling datasets, scientific data
> formats, etc.

I think you are talking of a very worthy goal. But I think this is not
the scipy user guide, this would be a book (maybe called "Python in
Science") that would give an introduction to the whole stack, and a
task-oriented approach with an overview of all the core packages.

This book cannot indeed be written by the community, as it requires a
consistent, well-thought, effort. On the other side, the scipy User Guide
is a bit more wikipedia-like. It is a searchable, and organised,
collection of technical documentation of each feature of SciPy, the
library. This can only be written and maintained by the community that
maintains SciPy. Especially since no one person knows SciPy well-enough
to do that.

My 2 cents,

Gaël



More information about the Scipy-dev mailing list