Python Documentation (should be better?)

[Steven Bethard]

Christopher J. Bottaro wrote:
> I think it should evolve into a manual that is more comprehensive
> and organized more like other programming manuals (chapter on control
> structures,

http://docs.python.org/tut/node6.html
  or
http://docs.python.org/ref/compound.html

> functions,

http://docs.python.org/tut/node6.html#SECTION006600000000000000000
http://docs.python.org/tut/node6.html#SECTION006700000000000000000
  or
http://docs.python.org/ref/function.html

> classes, inheritance, etc

http://docs.python.org/tut/node11.html
  or
http://docs.python.org/ref/class.html


Note that the first examples above are from the tutorial, the second 
form the language reference.

Personally, I would think that for 99% of users, going through the 
tutorial should be sufficient (it was for me).  I only use the language 
reference when I need to explain a particular detail of why Python does 
something.

Was there something that wasn't in the tutorial that you would have 
liked to be?  The more specific you can get, the more easily we can 
improve the documentation.

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

Well then at least file a feature request and indicate what was missing 
from the documentation, or what part of it confused you.  Even if you 
throw in a few phrases of documentation that never get used, at least 
they might give the dev who updates the documentation a better idea of 
the problem you encountered.

STeVe