[Tutor] Documentation concerns.

[Magnus Lyckå]

At 01:34 2003-05-23 -0300, Jorge Godoy wrote:
>There's no indication on, how to import the module ("import cgi"?
>"from cgi import *"?), on how to start a simple cgi with it, etc.

Perhaps you should look in the Python Library Reference? After
all, that would be the logical place to read about how to use
a python standard module.

Go to http://www.python.org/doc/current/lib/module-cgi.html
Click where it says "Using the cgi module" and read the first
sentence. I quote:

   Begin by writing "import cgi". Do not use "from cgi import *"

It certainly tells you how to import the module! In fact, if you
manage to type "help(cgi)" you *have already* managed to import
cgi correctly. Don't expect all of the docs to be in the source
code. Maybe it would be good if an IDE could invoke the right
part of the python manuals if you clicked on a word in the source
code and pressed F1, but that's a separate issue than documentation
contents.

It's possible that we'll see more and more of the documentation
being generated from the source code, but often, the ideal structure
of the implementation is not the ideal structure of documentation
of a module, so it's probably good to have separate documents.

I'm not so sure Perl's adaption of the unix manpage format for
system calls really fit whole modules like that. There are certainly
examples in the python docs, but you need to look in the module reference.
It's the document marked "keep this under your pillow" in the
documentation index... http://www.python.org/doc/current/index.html

Nothing is so good that it can't be improved though, so I really think
many of you could improve things a lot be providing improved
documentation. If nothing else, I'm sure you will learn a lot if
you actually read the existing docs properly, which I suggest that
you do before you try to improve them. ;)


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