[Tutor] Documentation concerns.

Jorge Godoy godoy@metalab.unc.edu
Sat May 24 08:14:01 2003

"Alan Gauld" <alan.gauld@blueyonder.co.uk> writes:

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

That's fine. Using, again, the perl example, when I type 'man module'
I get exactly the same output as when I type 'perldoc module'. And I'm
using the manual ;-)

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

I think that if this speed difference on importing the module is
relevant, than your application would benefit a lot from C code. Maybe
Python compile should also discard/ignore the code to reduce the
memory use.

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

This is also obvious to me. Where are my system's docs? Available in
man pages. Where do I think other things docs should be? In man pages
as well. Or info, which can have hyperlinks and consult both info and
man pages. 

One interface, all the docs. It was true with C, it was true with Perl
and I think that it could be true with Python. Why not? More
documentation is better than fewer 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

Well, I run Linux on a PC, so I suppose you were talking about
Windows. But, with regards to your question, it is true that some
Linux distributions have separate packages for the docs but if you get
Python's source from www.python.org, than everything is packaged
together and in any other operating system.

> have Python you automatically have the docs too. And both IDLE and
> Pythonwin have friendly help menus that launch the doc browers...

I use my system's standard tools a lot (info and man). It's something
like having a way to make python documentation searchable with Windows
Help. (I'm not guilty if Unix tools are easier to use in that case...)

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

We just have to find those instructions. They change from module to
module (except for the standard ones).

Godoy.    <godoy@metalab.unc.edu>