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

jh@physics.uc... jh@physics.uc...
Thu Dec 4 19:16:24 CST 2008


Jarrod wrote:

> I would also prefer changing the name from "Tutorial" to "User Guide".

I disagree, for two reasons.  First, we are badly diluting our doc
effort and will fail to complete *any* documents to a user's
satisfaction with this approach.  We need to close the scipy doc wiki
(maintainers can edit in SVN), pause on tutorials, and focus on the
task at hand.  First document the core software.  Then document its
general use.  Of course, I can't force anyone to do this, but I hope
you all will.  Together, we are more than the sum of our parts.
Separately, we cannot get this job done.

Second, a (good) user manual takes a level of planning and commitment
that has not gone into any of our documents so far.  This tutorial
document cannot grow into a good user manual, because documents
*never* improve with organic growth.  They must be planned and written
with scope in mind from the outset.  We should reserve the name "User
Manual" for something we plan and execute to be good with that scope.

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.  Heavy-duty programming chapters belong in a separate
document (NumPy Programmer's Guide?).  Advanced tricks need to be
limited in the User Guide or it will be far too long.  It could go in
its own guide, or might better go in a web cookbook.

We are a grass-roots community, but good books are not, and have never
been, written by a haphazard grass-roots effort, with everyone writing
whatever they feel like writing.  The best you can hope for is to
scope and plan as a community, set goals for specific docs and
sections of docs, form small groups of writers, parcel out pieces with
specific goals to different groups, and then have a small editing team
work with the chapter teams to unify the pieces.  This is a standard
process in academic publishing and it works well.  Other than the
small-team-does-it-all model, I'm not aware of any other successful
authoring modes.  Grass roots works on the doc wiki only because we've
provided strict guidelines and process, and each page is done by just
one or a few people.

If we don't plan as a community and focus our efforts, the scattered
docs will reflect the interests of the writers rather than the
readers.  The quality will be quite variable and key items will never
be finished.

Please everyone,
new things are fun, 
but let's first finish
what we've begun.

Go write numpy docstrings.

--jh--


More information about the Scipy-dev mailing list