[SciPy-user] [SciPy-dev] Re: [Numpy-discussion] Purchasing Documentation

[Fernando Perez]

Travis Oliphant wrote:

> Yes, yes.  Fernando knows me pretty well in that regard. I'll probably 
> contribute to it with useful selections from the book (once I have the 
> book finished).    It really motivates me to produce more  (of 
> everything) when I see people actually purchasing the documentation.

To reiterate before my reputation is tarnished forever: the bet was with John, 
who is the doughnuts-eating one.  Being a man of taste, I eat bagels :) [and I 
wasn't present when the bet was made]

With that critical point out of the way, on to minor details.

> It would be great if somebody could at least post the pydoc output for 
> the core.  That is a good start.  I'll add basic C-API calls to free 
> documentation and we'll be ready to go.

While I fully respect the opinion of those concerned about Travis' decision, I 
have to say that I am personally not so worried.  At scipy'05, when Travis 
announced the book idea, I asked a very simple question: 'are the docstrings 
complete?'.  His answer was 'yes'.

There was a good reason for my asking this question:  I personally find that 
when coding, the most productive and efficient to learn a library is by typing

import foo
foo.<TAB>

and then

foo.bar?

or

foo.bar??

if I want to see the source (for python-implemented things).

I understand that some people prefer to read manuals/books, and there are 
topics beyond the single-function API that are best discussed in a book 
format.  But given the instantaneous response of the above, I would rather use 
this than wade through an index in most cases.  In fact, I'd like docstrings 
to provide (simple) examples in them, and one thing on my radar now that 
ipython is growing GUI/XML legs is to add support for latex in docstrings.

I think that a library where all individual methods/functions have full, 
accurate and example-loaded docstrings, and where class declarations and 
top-level module docstrings provide the higher-level overview, is extremely 
usable as is.  Especially when you can also keep pydoc running in html server 
mode (pydoc -p) to browse at your leisure, and trivially dump that HTML info 
to disk for static reference if needed.

If this is done, I think that the space for a 'real book' is better defined, 
providing less of a detail reference and more of a teaching coverage.  I sense 
that this is Travis' approach, and I personally have no beef with it 
whatsoever.  If he had deliberately stripped or crippled all docstrings from 
new_scipy to artificially create a need for his book, that would be a 
different story.  But he certainly didn't do such a thing.

I do think that there's a lot of room for higher-level books on python for 
scientific computing.  Langtangen's is already out there, and Perry's 
excellent tutorial is already free for all to use (while slightly focused on 
astronomy, I find it a very useful document).

I guess what I'm trying to say is that the _library_ documentation can be 
considered to be a (good) set of docstrings.  As long as scipy ships with such 
a thing (which can be improved with the easiest of all patches by users, since 
no code is touched), I am not so worried that it will be perceived as lacking 
real docs.

Please note that I am not discussing the price/time constraints of his 
licensing, which is strictly his choice to make.

Again, this is just my _personal_ opinion.  And while I have great 
appreciation for Travis, he's not paying me to say any of this :)

Regards,

f