[Doc-SIG] Re: [Tutor] Documentation concerns.

[Jorge Godoy]

Guido van Rossum <guido@python.org> writes:

> But every project has its own constraints, and I can certainly
> understand why some projects prefer to have the full user
> documentation as docstrings.  I expect that such projects will still
> require some external documentation, e.g. a separate tutorial.

I was one of the people who suggested the documentation within the
module. 

Let me try, again, to explain :-)

What I think is a good thing to have is a concise document available
with the code so that if we have the code, we can just run something
like 'pydoc module' and see how to use the referred module. It could
(and IMO should) contain some example.

The idea is not put all the documentation that exists inside the
module. The idea is to put enough documentation to have a working
prototype or testing code. 

It may be a taboo here, but I made the comparison with the first page
of two modules: Perl's CGI and Python's CGI. 

I won't include the cited text again, it can be read from
python-tutor's archives or from your own systems.

The thing was that Perl's module included enough documentation to have
a start. There are more documents on the subject available in books,
on websites, etc. 

Python's module, on the other hand, gave me a description of the class
and its methods. Some of them had a nice description, other didn't. 

I'm not saying that consulting Python's standard docs (in this case
http://www.python.org/doc/current/lib/module-cgi.html) was too hard,
but it surely could be simpler. 

I use 'man' or 'info' to do read system docs, C docs, Perl docs. It
would be very interesting if something like 'pydoc' was integrated
with the system docs as is 'perldoc' and it would be even better if
the output of the documentation shown was enough to write a prototype
(even for a newbie as myself). 


<about standard library's docs>

>> Is this still gospel? Any further thoughts around this?
>
> This is still gospel for the Python standard library.

Let me make clear, here too, that this is not my intention to change
the existing docs. My intention was to add new stuff to modules so
that they can be easily understood with no additional material
(specially when people can install python in a 'defective' way without
its docs on embedded systems or production machines --- it saves 2.6
MiB here, what can be very significative in a 12 MiB flash card :-)).

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