[Tutor] Documentation concerns.

[Magnus Lyckå]

At 12:57 2003-05-22 -0600, Bob Gailer wrote:
>What I expect (or at least desire) is those few more words that tell me 
>what happens so I don't have to guess.

But you don't *have* to guess. You just have to *try*. This
is also a very relevant aspect of python. It's so simple to
fire up the interpreter (actually, there is always a running
Python interpreter on my machine) and try it out, just like
you obviously did.

Perhaps the Python documentation needs to contain even more
suggestions to try out and experiment with features.

On the other hand, It's very easy to forget how tricky things
might be before we get to grips with them. After all, most
things are trivial when we have understood them. The need for
the documentation if mainly to get there...but usually written
by those who long forgot how it was...

Perhaps it's a bad reflex to say that "this has nothing to
do with Python". Some time ago I suggested that some more
documentation was added concerning installation of pysqlite
on Linux as non-root, and I got the reply that this wasn't
really a pysqlite issue, so it didn't belong in their docs.

The thing was that I've been working with Linux since 1994
and with Python since 1997, and I've installed a number of
Python modules at my ISP where I don't have root access, and
pysqlite was the first time I ran into trouble, and had to
make a bigger effort to figure out what was wrong, and do
things differently than documented.

In deciding whether to put something in the docs or not, the
important issue is probably not whether it's "a python issue"
or not, but whether it will help the reader succeed in his
Python programming efforts or not.


--
Magnus Lycka (It's really Lyckå), magnus@thinkware.se
Thinkware AB, Sweden, www.thinkware.se
I code Python ~ The shortest path from thought to working program