[Tutor] Documentation concerns.

[Alan Gauld]

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

Because the author decided to put it there.

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

Depends on your background. As someone who has spent his
professional life using traditional languages like Pacal,
C and COBOL I would never dream of looking for documentation
in the module itself - that's what manuals are for!

I believe Smalltalk might have been the first to start putting
main docs in the code. Perl etc have followed this trend.
But I hate it! It makes the module code hard to read, it gets
obscured by all the "other stuff". It also makes the module take
longer to import, even if its only slightly. Big files are nearly
always a bad thing in programming and that includes modules.

As for the logical place. What could be more logical than that
the documentation is found in the documentation? Seems to me far
more logical to keep the documents with all the other documents
than in the code - which is logically executable not readable!.
Therefore I always go to the documents for documentation!

And of course one of the good things about Python is the quality
of the documentation that you get with the interpreter(on Mac
and PC at least - I think Linux keeps them as separate downloads?)
So if you have Python you automatically have the docs too. And both
IDLE and Pythonwin have friendly help menus that launch the doc
browers...

Not to say the docs can't be improved, they can, and the instructions
for doing so are also included, in the documents! :-)

Just my 2 cents,

Alan G.