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

jh@physics.uc... jh@physics.uc...
Sat Dec 6 11:28:13 CST 2008


> Pauli Virtanen <pav@iki.fi> writes:

> > Second, a (good) user manual takes a level of planning and commitment
> > that has not gone into any of our documents so far.

> I don't think it's fair to say that no planning has been done. 

I didn't!

> The 
> content of the Numpy reference guide is based on Travis's work, and I 
> streamlined it by editing out the user-guidish parts.

> Criticism is of course welcome, but it's more helpful to be specific.
> I have seen little to no feedback on this.

I'm not criticizing your work at all, Pauli.  I'm saying that the
document I call User Guide needs to follow a different path from any
we've taken so far.  I outlined this process, used widely in academic
publishing, in a prior post.  For example, we used it in writing this
book:

http://www.amazon.com/Jupiter-Satellites-Magnetosphere-Cambridge-Planetary/dp/0521035457/ref=pd_bbs_sr_3?ie=UTF8&s=books&qid=1228583542&sr=8-3

The organizer held a conference at which chapter topics were
discussed.  She got a publisher (CUP) and then put out an RFP for
additional editors and chapter teams.  Teams proposed to take on
chapters.  She selected two more editors and they selected among the
proposals for each chapter.  I think a few shotgun marriages were
arranged between proposal teams, etc.  We (I led chapter 8, on the
1994 Shoemaker-Levy 9 comet impact) got guidelines and a latex format,
and a set of (teflon-coated) deadlines.  We wrote.  They sent the
chapters out to three reviewers.  We revised, were re-reviewed,
resubmitted.  They sent out lists of consistency issues.  We fixed
them.  A professional indexer went through the whole book and did the
index.  We sent it to Cambridge Univ. Press, which printed it.  I am
quite proud of both my own chapter and the degree of integration we
were able to achieve across the whole volume.  This is now The Book on
Jupiter.

I don't expect we'll start on this volume until at least two years
from now, based on our rate of progress on the docstrings, but I
propose we use the academic process outlined here.  For our case, we
don't need to have a commercial publisher (but could, with appropriate
license), and we can put the chapter drafts online for a public review
in addition to getting expert reviews.

--jh--


More information about the Scipy-dev mailing list