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