Python reference

[Neil Benn]

Hello,
         
          I've kept quiet about the Python documentation up till now but 
after some experience, I have a few comments - I do hope that they 
help.  Firstly my experience : my main language is Java (also VB, 
Pascal, small amount of C/C++, C#) but I've learnt Python after coming 
to a new job. 
    Generally the documentation is good, remembering that this is an 
open-source project and most people hate doing documentation there is a 
lot of good documentation available and the books are pretty good.  
However there problem that I've had most frequently  is actually finding 
the information I need (personally I don't like the 'everyone 
contribute' type of documentation as there can be a lot of clutter and 
repetition).  I think the module index is OK but there are fundamental 
things missing.  For example, I have a String object and want to find a 
method that can give me a starts with.  Before people say I can type 
dir("IT'S OBVIOUS") or simply just guess (is it startswith, starts_with, 
StartsWith, etc - that's before I get to the parameters), let's assume 
that I'm coming from a language without an interepter - say Java, C#, 
VB, C/C++, Pascal, etc.

    So, following behavior of docs I would expect from other language's, 
I go to the module index and it gives me the definitions for all the 
functions for the String 'module' but not the String 'object'.  So, 
thinking - OK, it a could be in the language ('library') reference, I'll 
look in there - I know that a String is a sequence so it may have a 
reference there but I get a link back to the string module.

    (I know there are historical things surrounding this but again a 
beginner in Python would not know this)

    Personally I now know that it can be worked out by persevering and 
so on - so I don't need this information anymore because I know it and I 
can use the docs installed on a win32 python dist (which has searching) 
BUT a beginner will instinctively apply the knowledge they have from 
other areas and look on python.org.

    For an example of what I'm thinking about, take a look at the J2SE 
docs :-

    http://java.sun.com/j2se/1.4.2/docs/api/index.html

    I hope that this is taken in a spirit of _constructive_ criticism, 
AFAIK pyDoc can do this type of thing already - would it be an idea to 
put a pyDoc type language reference on the python.org webpage?

    Obviously your behavior will be different if you are coming from a 
different language but I've never used PHP, Perl, etc - I've come at 
this from a different direction.

Cheers,

Neil

-- 

Neil Benn
Senior Automation Engineer
Cenix BioScience
BioInnovations Zentrum
Tatzberg 47
D-01307
Dresden
Germany

Tel : +49 (0)351 4173 154
e-mail : benn at cenix-bioscience.com
Cenix Website : http://www.cenix-bioscience.com