Python Documentation (should be better?)

[Christopher J. Bottaro]

Steven Bethard wrote:

> Christopher J. Bottaro wrote:
>> After we were done, we talked about the pros and cons of the languages.
>> Funny, the con of Python (documentation) is PHP's strong point.  The PHP
>> manual is extremely easy to navigate and its search feature works great.
>> Contrast that with Python, where you have to use "the tutorial" as the
>> manual.  Also, the tutorial is just that...a tutorial, its a NOT a
>> manual. Its not organized like a manual and its not comprehensive like a
>> manual, hell, raw_input() isn't even mentioned in Chapter 7. Input and
>> Output.
>> 
> [snip]
>> 
>> What do yall think?
> 
> I have to say, I don't really have your troubles with the documentation,
> and I hardly ever use dir() in the interactive shell.  You mention only
> referring to the tutorial.  Why don't you check the Language
> Reference[1] or Library Reference[2]?

Cuz I think the Language Reference is really more of a grammer reference and
far too technical to look up simple things like "how to declare a
function".

I guess what I'm trying to say is that there is no manual (for the language
itself, not the modules).  There is just the tutorial that serves as the
manual.  I think it should evolve into a manual that is more comprehensive
and organized more like other programming manuals (chapter on control
structures, functions, classes, inheritance, etc).

Kinda funny...I was going to use the email module as an example of a module
that lacks examples...but apparently that has been updated since when I
last used it...=)

> That said, if you see spots where the documentation needs help, the
> right answer is to file a feature request[3] to add documentation.  If
> you're feeling especially helpful, providing the documentation you'd
> like to be added would be greatly appreciated.  Python's a community
> effort -- if you see weak points, you can help the community build a
> better Python by taking the time to address them yourself.

That true, but to be perfectly honest...I don't feel qualified.  I'm still a
young'un in this programming game.  I'm sure a lot of seasoned devs would
scoff at the documentation I write.

> STeVe

-- C

> [1]http://docs.python.org/ref/ref.html
> [2]http://docs.python.org/lib/lib.html
> [3]http://sourceforge.net/tracker/?group_id=5470&atid=355470