Unhappy with numarray docs

[Matt Feinstein]

I spent all day yesterday trying to figure out how to do file IO in
the numarray module-- I -did- (I think) figure it all out, eventually,
but it's left me in a rather sour mood.

1. The basic functions and methods: fromfile, fromstring, tofile, and
tostring, are buried, in non-alphabetical order, in two chapters that
list -all- the functions and methods. This is not user-friendly. The
explanations themselves, once I found them, are OK, but a line or two
of sample code is always nice. File IO is a real-world necessity in an
environment where most people use Matlab and/or IDL. And is it
obvious, btw, that reading data should be a function? What if I want
to read into a buffer?

2. The memmap documentation is screwed up in a more serious fashion. I
was able to deduce relatively rapidly that

from numarray.memmap import *

was needed for some of the example code. But I didn't immediately have
the degree of clairvoyance needed to figure out that

import numarray.numarryall as num

was required for the critical step of associating an array with a
MemmapSlice. Grr.

Matt Feinstein

 

[Scott David Daniels]

I spent all day yesterday trying to figure out how to do file IO in
the numarray module-- I -did- (I think) figure it all out, eventually,
but it's left me in a rather sour mood.

.... Grr.

Propose some fixes to the documents that will make this easier for
the next one in line. You don't even need to get it exactly right;
the person after you can fix the mistakes you make. This is the
process we use for this. See this as an opportunity to contribute,
not simply a frustration about how much you overpaid for the product.

--Scott David Daniels
(e-mail address removed)

 

[Matt Feinstein]

Propose some fixes to the documents that will make this easier for
the next one in line. You don't even need to get it exactly right;
the person after you can fix the mistakes you make. This is the
process we use for this. See this as an opportunity to contribute,
not simply a frustration about how much you overpaid for the product.

Which is why I was specific about what I didn't like about the
documentation and why I didn't like it. Seriously, what more should I
do? It's plainly inappropriate for me to write documentation for a
module that I'm still struggling to learn.

Matt Feinstein

 

[Fernando Perez]

Which is why I was specific about what I didn't like about the
documentation and why I didn't like it. Seriously, what more should I
do? It's plainly inappropriate for me to write documentation for a
module that I'm still struggling to learn.

Just a suggestion: post your message on the numeric discussion list (where
numarray is also discussed). Most of the num* developers only check c.l.py on
occasion, so it's very easy that your message will be simply missed by the
appropriate people, which would be a shame. They are generally very
responsive to user requests and constructive criticism.

best,

f

 

[Matt Feinstein]

Just a suggestion: post your message on the numeric discussion list (where
numarray is also discussed). Most of the num* developers only check c.l.py on
occasion, so it's very easy that your message will be simply missed by the
appropriate people, which would be a shame. They are generally very
responsive to user requests and constructive criticism.

Done. Thanks for the suggestion.

Matt Feinstein

 

[Terry Reedy]

Which is why I was specific about what I didn't like about the
documentation and why I didn't like it. Seriously, what more should I
do?

If your suggestion is 'small', you can write a suggested sentence or two
and post in on the appropriate forum. Something like 'In section xx.y, 2nd
para, I wish there had been a sentence saying something like 'connect the
frog to the jib and the jib to the boom'. With something like that to go
on, an expert can verify and possibly insert/replace. I have done this for
the Python docs.

It's plainly inappropriate for me to write documentation for a
module that I'm still struggling to learn.

You know better than any expert where you got lost and what you wish had
been said ;-)

Terry J. Reedy