[Tutor] Documentation concerns.

[Jorge Godoy]

Magnus Lyck=E5 <magnus@thinkware.se> writes:

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

So, if there's the logical place, why some documentation is on the
module itself?

I think that the module is the logical place and the Python Library
Reference is the *second* logical place to look at. I already have the
module.

> It certainly tells you how to import the module! In fact, if you

I have already written some applications with the CGI module. The
point is that the documentation that we have available (and searchable
with pydoc -k) is not as intuitive as it should be.

If I have some application, I certainly have the module but it's not
guaranteed that I'll have net access or a copy of the Python Library
Reference with me.

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

My IDE is Emacs + several xterms. :-) Using pydoc is really great. As
is perldoc, texdoc, etc.=20


We were discussing ways to improve the documentation --- at least
that's what I understood from prior messages --- and having complete
docs with the module including explanations on simple use --- maybe
even complex use --- of it would greatly enhance the productivity.=20

I was not --- this time ;-) --- looking for the docs (you see, even
having read --- actually I just passed my eyes on everything, but I
read whole parts of it --- he whole Python Library Reference I still
have to look at or question for the places where docs are).=20

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

Standardizing places to find docs is something every project
needs. Python has done that.=20

Unfortunately, putting every single modules documentation in a website
is not what I think is ideal. Having the docs with the module makes
them look like part of the code --- IMHO they are as important as the
code itself --- and makes the author of the module update them with
every change he does in the code.

> 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

I'd rather have something that is "kept with the working
module". Really. Perl gives that and it is incorporated in Perlers
coding style.=20

I see no reason it can't be done with Python. There's everything
there, it is just needed to add some more text at the beginning and
some parts of the code, no changes in standard modules are needed.=20

> 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. ;)

I'm reading a lot of the docs I could find. There are lots of things
at Python's website but there are lots of things spread all around.

And, you can bet that if I could I'd change several
standard/non-standard modules documentation to add examples and make
some information available with the source code. If the documentation
needed is too big, adding a message like 'For complete documentation
on this module look at http://somewhere.over.the.net/modules-doc'.=20


Sometimes it takes a body of new people to point out something that
people are already used to see and use can be improved. I wouldn't
discard any opinions even if I had to point them out the docs that say
why the way it is now is better than the proposed way. All have to
learn with such discussions: the ones wanting to change and the ones
saying that changing is not needed.

You certainly have more python experience than I do. I was just
looking at it in the last two years, I haven't written much code in it
and then, when I started doing such a thing, I found out that there's
a HUGE difference in the documentation style used in modules. I don't
know, yet, if Perl's way is much better than Python's way on that
issue, but it certainly is more practical to work with, after all, as
you pointed out, typing 'help(module)' is much easier than opening a
browser, going to the python library reference or doing a search on
the web...


--=20
Godoy.    <godoy@metalab.unc.edu>