benn at cenix-bioscience.com
Fri Jun 4 11:13:43 CEST 2004
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
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.
Senior Automation Engineer
Tel : +49 (0)351 4173 154
e-mail : benn at cenix-bioscience.com
Cenix Website : http://www.cenix-bioscience.com
More information about the Python-list