[Numpy-discussion] NumPy documentation

[eric jones]

Travis Oliphant wrote:

>
> I received a rather hurtful email today that was very discouraging to 
> me personally.  Basically, I was called "lame" and a "wolf" in sheep's 
> clothing because I'm charging for documentation.    

Hmmmm....


Chickens getting eaten by foxes.
Farmer builds wire coop.
Coop destroyed by foxes.
More chickens eaten.
Wolf builds wooden coop for free.
Also stands guard but for a fee.
No more chickens eaten.
Most chickens glady pay.
A few grumble about extortion!
Thats fine.
Let them take the guard.
Foxes aren't so afraid of Chickens.
This chicken will take his chances with this wolf.
Turns out its just a lame chicken in wolves clothing.
Smart chicken, he is.

Dumb letter.  Dumb story.

Let see here, your a chicken.  check.  Travis is smart wolf-chicken... 
yeah that works. 
Numpy is the wooden chicken coop. errr... Guard duty is documentation. 
hmmm...
foxes, not sure...  Guess I should keep my day job.


Slightly more seriously...

There's a chicken's foot full of people on the planet that could have done
what Travis has pulled off -- I've actually thought about this a 
little.  Maybe
Jim Huginin could have done it given similar time and motivation.
After that, I come up a little short of candidates -- so maybe its just 
a pigs foot full.
I consider us lucky that one of the few people able to fuse Numeric/numarray
bailed us out and did it.

Documentation is another matter as far as scarcity of qualified 
authors.  I would
trust any number of yayhoos to create
at least passable documentation for Travis' creation. Heck, David Ascher 
managed
to write the Numeric documentation <wink>.  That said, writing docs is 
work,
hard to do well, and not nearly as much fun as writing actual code (for the
people on this list anyway).  That significantly lowers the probability 
of it
getting done.  In fact, I believe LLNL funded the first documentation 
effort to help
ensure that it happened (though I'm not positive about that). 

And, think of the creek we'd be up if he chose to keep the library and 
give away the docs.

I'm all for someone writing free documentation.  It'd be great to have.  
And, if
it were as good as Travis', I might even use it.  Still, it would 
probably be
better for the world if you spent your time on other things that don't 
already
have a solution (like documenting SciPy...).  Once that and all similar 
problems
are solved, loop back around and do the NumPy docs.

One other comment.  I've used another amazing library called agg
(www.antigrain.com) extensively for rendering in kiva/chaco.  I view 
Maxim (the
author of Agg) and graphics rendering in a similar light as Travis and 
Numpy --
there are only a handful of people that could have written agg.  For 
that I am
hugely greatful.  On the downside, agg is very complex and has very little
documentation.  Still a number of people use it without complaint. Based 
on the
evidence, if Maxim wrote documentation and charged for it, the number of
complaints would actually increase.  It is just silly. I would pay his 
price and
sing his praises for the days of my life that he gave back to me.

eric


ps.
# Based on a definitive monte carlo simulation, one of every hundred 
chickens will
# complain.  Don't believe me.  Try it.

dist = stats.uniform(0.0, 1.0)
for chicken in chickens:
    if dist.rvs()[0] < 0.01:
        print "extortion"