Python Documentation (should be better?)

2 views
Skip to first unread message

Christopher J. Bottaro

unread,
May 11, 2005, 2:50:36 PM5/11/05
to pytho...@python.org
This post is just the culmination of my thoughts and discussions with my
coworkers on Python. If you are not interested, please skip over it.

At my work, we are developing a product from scratch. It is completely
modular and the modules communicate via SOAP. Because of that, we can
implement individual modules in any language of our choosing (so long as
they have good SOAP libs). I chose to do all mine in Python because I'm a
huge Python fan boy. Naturally, I tried to get my coworkers to try Python.
I made an agreement with one: I write one of my modules in PHP and he will
write one in Python.

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.

Now for the real kicker. Some of the module documentation doesn't even list
simple use cases or even the entire API. When my coworker came to me with
this complaint, my response was "oh, just load the interpreter, import the
module and call dir() on it. Then instantiate some objects and call dir()
on them also". My infatuation with Python had kept me from realizing the
sheer ridiculousness of that method to learn to use an API. Needless to
say, my coworker's reaction to that statement snapped me out of it. But
its the truth. How many of you learn a module by starting the interpreter
and "playing" around with it and using dir()?

The next complaint isn't really about documentation. Why isn't there a CPAN
or PEAR for Python? So many times I've search for a module, not found it,
started to write it myself, then later stumble across it on Google...ugh!

Don't get me wrong, I love Python. The language itself is second to none (I
haven't tried Ruby yet), but this experience has left me wondering about
the future success of Python. Even I, a huge Python advocate, has started
to use PHP more often simply because I can find well documented,
semi-official modules very easily and learning PHP is a breeze with the
awesome PHP manual.

What do yall think?

Christopher J. Bottaro

unread,
May 11, 2005, 3:02:42 PM5/11/05
to pytho...@python.org
Christopher J. Bottaro wrote:

> ...blah blah blah...

Heh, silly me...there is already a huge thread about this...kinda.

The intricacies of the computing term "greedy" aside, yes I think the Python
documentation should generally be better. What that means, I have no idea.
All I know is that I like PHP's documentation and it should be like that.
My question is, why is PHP's documentation so good and Python's mediocre?
Does it have to do with corporate backing (I have no idea if PHP is or not,
I'm just saying)? The quality/quantity of volunteers? The design of the
language itself?

hug...@gmail.com

unread,
May 11, 2005, 3:21:11 PM5/11/05
to
I think Python's doc really rock. It's odd, why do you refer to the
tutorial when the lib API is what I'd consider "the docs".

If you're using Windows, then the doc browser included is pretty good
too...

Skip Montanaro

unread,
May 11, 2005, 3:27:46 PM5/11/05
to Christopher J. Bottaro, pytho...@python.org

Christopher> The intricacies of the computing term "greedy" aside, yes I
Christopher> think the Python documentation should generally be better.
Christopher> What that means, I have no idea. All I know is that I like
Christopher> PHP's documentation and it should be like that.

It would help if you could narrow the scope down a bit. ;-) Can you spend a
little time comparing and contrasting the online Python and PHP docs and
make some specific comments?

Christopher> My question is, why is PHP's documentation so good and
Christopher> Python's mediocre?

I don't think it's so much that Python's documentation is mediocre. I think
most of what you need is there (I count about 110k lines of LaTeX source
split over a hald dozen chunks of documentation). It may be that it's not
all that well organized for online searching/contribution/annotation. It's
more book-like. That may be largely due to the fact that it's written in
LaTeX which doesn't lend itself well to a highly interactive end result.

Google helps. If you search for the terms you're interested in at
http://docs.python.org/ your search will be restricted to the official
online docs. That might help a bit. Also, I find the module index to be
the most useful bit of documentation to have handy:

http://docs.python.org/lib/modindex.html

Christopher> Does it have to do with corporate backing (I have no idea
Christopher> if PHP is or not, I'm just saying)? The quality/quantity
Christopher> of volunteers? The design of the language itself?

There does seem to be a very high ratio of people who complain about the
documentation to people who write the documentation. Many of us with little
time but a modicum of LaTeX knowledge are willing to mark up plain text
patches to the documentation.

If you're interested in seeing what's going in in the Python documentation
world, browse the doc-sig's archives:

http://mail.python.org/pipermail/doc-sig/

Skip

Sébastien Boisgérault

unread,
May 11, 2005, 3:31:35 PM5/11/05
to
Christopher J. Bottaro wrote:
> [...]

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

The tutorial is great IMHO and yes, it is definitely not a
reference guide. But what's wrong with the online library
reference or its pdf equivalent ? And why don't you use the
python.org "search" (top right of the screen) ?

> Now for the real kicker. Some of the module documentation doesn't
> even list simple use cases or even the entire API.

Sometimes the 'missing' interface is (superficially) hidden
on purpose. Example in doctest about the DocTestCase class
(quoted from the library ref) :

"""
Under the covers, DocTestSuite() creates a unittest.TestSuite out of
doctest.DocTestCase instances, and DocTestCase is a subclass of
unittest.TestCase. DocTestCase isn't documented here (it's an internal
detail), but studying its code can answer questions about the exact
details of unittest integration.
"""

Could you be more specific about the modules/packages
that lack proper examples/documentation ?

> When my coworker came to me with
> this complaint, my response was "oh, just load the interpreter,
> import the module and call dir() on it. Then instantiate some
objects
> and call dir() on them also". My infatuation with Python had kept me

> from realizing the sheer ridiculousness of that method to learn to
> use an API. Needless to say, my coworker's reaction to that
statement
> snapped me out of it. But its the truth. How many of you learn a
> module by starting the interpreter
> and "playing" around with it and using dir()?

You may also use "help" instead of "dir", or directly
pydoc in a shell:

python>>> help("math")
python>>> help(math) # if 'math' has already been imported
bash$ pydoc math

This kind of documentation system suits me (it is far better
than a raw dir anyway). It supports a 'dotted reference'
description of the path to the objects (ie
package.subpackage.module.holder.object) that is IMHO very
convenient.

Cheers,

SB

Steven Bethard

unread,
May 11, 2005, 3:33:32 PM5/11/05
to
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]?

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.

STeVe

[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

Christopher J. Bottaro

unread,
May 11, 2005, 3:41:03 PM5/11/05
to pytho...@python.org
hug...@gmail.com wrote:

> I think Python's doc really rock. It's odd, why do you refer to the
> tutorial when the lib API is what I'd consider "the docs".

I guess I mean Python needs a manual, which is basically what the tutorial
serves as, but its not comprehensive and organized like how (I think) a
manual should be.

Christopher J. Bottaro

unread,
May 11, 2005, 3:54:45 PM5/11/05
to pytho...@python.org
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

rbt

unread,
May 11, 2005, 3:58:04 PM5/11/05
to
Christopher J. Bottaro wrote:
> Christopher J. Bottaro wrote:
>
>
>>...blah blah blah...
>
>
> Heh, silly me...there is already a huge thread about this...kinda.
>
> The intricacies of the computing term "greedy" aside, yes I think the Python
> documentation should generally be better. What that means, I have no idea.
> All I know is that I like PHP's documentation and it should be like that.
> My question is, why is PHP's documentation so good and Python's mediocre?

Because PHP is such a 'thrown together' and 'bolted-on' language. If it
didn't have *outstanding* documentation (which it does BTW), no one
could even begin to understand how they got from a little HTML language
to a kinda/sorta OO language.

PHP is showing its age... thanks to its docs, it's still *extremely* useful.

Sébastien Boisgérault

unread,
May 11, 2005, 4:00:59 PM5/11/05
to

"Manual" == scope of the *Lib Reference* + informal style of the
*Tutorial*,

Right ?

Consider non-official manuals such as:
+ http://diveintopython.org/toc/index.html (free)
+ python in a nutshell
+ python cookbook
+ etc.

Cheers,

SB

Shi, Jue

unread,
May 11, 2005, 4:05:40 PM5/11/05
to Christopher J. Bottaro, pytho...@python.org

I agree. The PHP manual is really good, especially the examples and user
contributed notes.
I think that's why we need the reference manual most time. It help you to
get started on that particular function as well as hint you the trick and
trap.

I really wish Python manual gets better on these two areas.
Is it feasible to write a program to search the mailing list for example and
discussion related to particular function and archive it right under the
session of the manual. Anyone want to start this project?

Maybe a mailing list or forum people can contribute example and notes?

Just a thought.
Jue


-----Original Message-----
From: python-list-bounces+jue_shi=or.mx...@python.org
[mailto:python-list-bounces+jue_shi=or.mx...@python.org]On Behalf Of
Christopher J. Bottaro
Sent: Wednesday, May 11, 2005 11:51 AM
To: pytho...@python.org
Subject: Python Documentation (should be better?)


This post is just the culmination of my thoughts and discussions with my
coworkers on Python. If you are not interested, please skip over it.

At my work, we are developing a product from scratch. It is completely
modular and the modules communicate via SOAP. Because of that, we can
implement individual modules in any language of our choosing (so long as
they have good SOAP libs). I chose to do all mine in Python because I'm a
huge Python fan boy. Naturally, I tried to get my coworkers to try Python.
I made an agreement with one: I write one of my modules in PHP and he will
write one in Python.

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.

Now for the real kicker. Some of the module documentation doesn't even list
simple use cases or even the entire API. When my coworker came to me with


this complaint, my response was "oh, just load the interpreter, import the
module and call dir() on it. Then instantiate some objects and call dir()
on them also". My infatuation with Python had kept me from realizing the
sheer ridiculousness of that method to learn to use an API. Needless to
say, my coworker's reaction to that statement snapped me out of it. But
its the truth. How many of you learn a module by starting the interpreter
and "playing" around with it and using dir()?

The next complaint isn't really about documentation. Why isn't there a CPAN


or PEAR for Python? So many times I've search for a module, not found it,
started to write it myself, then later stumble across it on Google...ugh!

Don't get me wrong, I love Python. The language itself is second to none (I
haven't tried Ruby yet), but this experience has left me wondering about
the future success of Python. Even I, a huge Python advocate, has started
to use PHP more often simply because I can find well documented,
semi-official modules very easily and learning PHP is a breeze with the
awesome PHP manual.

What do yall think?

--
http://mail.python.org/mailman/listinfo/python-list

Skip Montanaro

unread,
May 11, 2005, 4:18:45 PM5/11/05
to Shi, Jue, pytho...@python.org, Christopher J. Bottaro

Jue> Maybe a mailing list or forum people can contribute example and
Jue> notes?

Contributions can be made at the SourceForge patch tracker:

http://sourceforge.net/tracker/?group_id=5470&atid=305470

Plain text is fine.

Skip

Steven Bethard

unread,
May 11, 2005, 4:18:36 PM5/11/05
to
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

F. Petitjean

unread,
May 11, 2005, 4:24:15 PM5/11/05
to
Le Wed, 11 May 2005 15:58:04 -0400, rbt a écrit :

> Christopher J. Bottaro wrote:
> Because PHP is such a 'thrown together' and 'bolted-on' language. If it
> didn't have *outstanding* documentation (which it does BTW), no one
> could even begin to understand how they got from a little HTML language
> to a kinda/sorta OO language.

+1 QOTW

Sébastien Boisgérault

unread,
May 11, 2005, 4:25:54 PM5/11/05
to

Christopher J. Bottaro wrote:

> [...]

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

Fair enough. An 'upgraded' tutorial that would include simple
discussion on some 'advanced topics' could be helpful. For example,
there is (almost) no reference to the new-style classes inside the
tutorial, the "yield" keyword and generator stuff is described in
half a page, etc.

SB

Ivan Van Laningham

unread,
May 11, 2005, 4:28:15 PM5/11/05
to Python Mailing List
Hi All--
The Python docs are not ideal. I can never remember, for instance,
where to find string methods (not methods in the string module, but
methods with ''), but I can remember a tortured path to get me there
(yes, I know, fix my brain; easier said than done). The module index is
good, if what you're looking for is in a module. The tutorial is good.

I can usually end up where I want to be by picking up my copy of _Python
in a Nutshell_. 95% of the time I can find what I want in there or from
there. The other 5% is too new, in the _Python Cookbook_ or in a
third-party module/lib. Or it's what I'm trying to write;-)

Metta,
Ivan
----------------------------------------------
Ivan Van Laningham
God N Locomotive Works
http://www.andi-holmes.com/
http://www.foretec.com/python/workshops/1998-11/proceedings.html
Army Signal Corps: Cu Chi, Class of '70
Author: Teach Yourself Python in 24 Hours

Sébastien Boisgérault

unread,
May 11, 2005, 4:42:17 PM5/11/05
to

> I can usually end up where I want to be by picking up my copy of
_Python
> in a Nutshell_. 95% of the time I can find what I want in there or
from
> there.

This book is really great. Could anybody convince Alex Martelli to
basically make it freely available to the world ? <0.9 wink>.

I would gladly pay the price of the book to make it free !

... just dreamin' ...

SB

flamesrock

unread,
May 11, 2005, 4:42:26 PM5/11/05
to
I don't know what you guys are talking about!!

In idle:

help(module)


I love the way python handles documentation. Its not invansive

Christopher J. Bottaro

unread,
May 11, 2005, 4:42:49 PM5/11/05
to pytho...@python.org
Sébastien Boisgérault wrote:

>
> "Manual" == scope of the *Lib Reference* + informal style of the
> *Tutorial*,
>
> Right ?

Yes! That sounds good. "Informal style" yes, but "tutorial style" no. I
shouldn't be there to teach like the tutorial, but for reference. And of
course, the manual shouldn't cover the modules like the lib reference does,
but just the language itself and "built in" types.

Ok, here is a concrete example of what I like about the PHP manual and what
people I know have had a hard time with Python. Go to the PHP manual page.
Type "array" in the search input field. It comes back with a page that
briefly describes arrays in PHP and then lists all the functions that have
to do with arrays.

Contrast that with Python. First off there is no "search" mechanism built
into the documentation page (yes I know you can google it, but that just
doesn't feel right). Second off...well, my argument sucks because I
apparently I haven't looked at the Python tutorial recently. But before,
if you looked up "lists" in the tutorial, you got a tutorial style page on
them. If you wanted to see their methods, you had to completely back out
of the tutorial, go to the library reference, then find the section on
"mutable sequences". How unintuitive is that? But like I said, the
tutorial is better now. It lists the methods on list and there is a link
in the dictionary section to the "mapping types" section in the library
reference.

Oh well, I guess all is well.

-- C

George Sakkis

unread,
May 11, 2005, 4:45:41 PM5/11/05
to
> 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).

If what you miss mostly is a quick way to look up language features,
modules and APIs, the python quick reference is an excellent starting
point, especially for someone new to the language:
http://rgruet.free.fr/PQR24/PQR2.4.html (also linked from
http://www.python.org/doc/ along with other doc sources). It's
available in pdf as well.

George

Steven Bethard

unread,
May 11, 2005, 4:52:06 PM5/11/05
to
Ivan Van Laningham wrote:
> The Python docs are not ideal. I can never remember, for instance,
> where to find string methods (not methods in the string module, but
> methods with '')

Hmmm... Well going to http://docs.python.org/ and typing "string
methods" into the search box gives, as the first hit:

http://docs.python.org/lib/string-methods.html

Even if you just search for "string", that URL is the second hit, and
pretty clearly the right one from the title.

STeVe

Steven Bethard

unread,
May 11, 2005, 4:54:41 PM5/11/05
to
Christopher J. Bottaro wrote:
> Contrast that with Python. First off there is no "search" mechanism built
> into the documentation page (yes I know you can google it, but that just
> doesn't feel right).

Um, are you looking at the current documentation page?

http://docs.python.org/

In the upper right hand corner, I see a box entitled "Search:" and a
button that says "submit".

STeVe

Christopher J. Bottaro

unread,
May 11, 2005, 4:47:11 PM5/11/05
to pytho...@python.org
rbt wrote:

Exactly!! See thats what I'm saying. I _think_ its widely accepted that
PHP has awesome documentation. And like rbt said, that makes it extremely
useful. Why can't Python have documentation like that? The language is
awesome, it just needs documentation of the same quality.

I'm sorry that I have such a hard time giving specific examples and what
not. All I can do (as of now) is kinda report the vibe I get...which is
completely useless, I know...=)

-- C

Bruno Desthuilliers

unread,
May 11, 2005, 5:40:02 PM5/11/05
to
Ivan Van Laningham a écrit :

> Hi All--
> The Python docs are not ideal. I can never remember, for instance,
> where to find string methods (not methods in the string module, but
> methods with ''),

>>> dir('')
['__add__', '__class__', '__contains__', '__delattr__', '__doc__',
'__eq__', '__ge__', '__getattribute__', '__getitem__', '__getnewargs__',
'__getslice__', '__gt__', '__hash__', '__init__', '__le__', '__len__',
'__lt__', '__mod__', '__mul__', '__ne__', '__new__', '__reduce__',
'__reduce_ex__', '__repr__', '__rmod__', '__rmul__', '__setattr__',
'__str__', 'capitalize', 'center', 'count', 'decode', 'encode',
'endswith', 'expandtabs', 'find', 'index', 'isalnum', 'isalpha',
'isdigit', 'islower', 'isspace', 'istitle', 'isupper', 'join', 'ljust',
'lower', 'lstrip', 'replace', 'rfind', 'rindex', 'rjust', 'rstrip',
'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title',
'translate', 'upper', 'zfill']

HTH

Steven Bethard

unread,
May 11, 2005, 6:29:45 PM5/11/05
to

Probably more useful:

py> help(str)
Help on class str in module __builtin__:

class str(basestring)
| str(object) -> string
|
| Return a nice string representation of the object.
| If the argument is a string, the return value is the same object.
|
...
|
| capitalize(...)
| S.capitalize() -> string
|
| Return a copy of the string S with only its first character
| capitalized.
|
| center(...)
| S.center(width[, fillchar]) -> string
|
| Return S centered in a string of length width. Padding is
| done using the specified fill character (default is a space)
|
...
|
| upper(...)
| S.upper() -> string
|
| Return a copy of the string S converted to uppercase.
|
| zfill(...)
| S.zfill(width) -> string
|
| Pad a numeric string S with zeros on the left, to fill a field
| of the specified width. The string S is never truncated.
...


STeVe

Steven Bethard

unread,
May 11, 2005, 7:02:09 PM5/11/05
to
Shi, Jue wrote:
> I agree. The PHP manual is really good, especially the examples and user
> contributed notes.

Dunno if anyone's spent much time editing this, but a while a go AMK posted:

http://www.amk.ca/diary/archives/cat_python.html#003336

which puts a wiki side-by-side with the Python docs:

http://pydoc.amk.ca/frame.html

STeVe

Ivan Van Laningham

unread,
May 11, 2005, 7:38:36 PM5/11/05
to Python Mailing List
Hi All--
Yes. There are multiple ways I can correct myself, some, I'm sure,
involving chains and whips. But you're all missing the point:
Christopher is right! Python docs are not as good as PHP docs. Why
not? Why do I have to be told "Hey, there are fifty ways to get what
you want!" when I should be able to go to the main doc page and SEE the
right link to click. Why isn't there a "Methods in Standard Objects"
page, for instance? Why would I have to search?

And the search is sucky, anyway. So there;-) Christopher described the
right way. I should be able to type "string methods" into the text box,
push submit, and IT SHOULD HAND ME THE PAGE. Not "Results 1 - 20 of
about 9,800 from www.python.org for string methods. (0.78 seconds)" (and
no, I am not exaggerating). And the first hit is from Python 2.1.3, NOT
the current doc. Sorry. No cigar.

"There's Only One Way to Do It," except in the Docs, that is. Good as
Google is, it is not good for a doc search. We don't have a doc search,
we have a doc hurl.

BTW, my "tortured method" is quicker than Bruno's, because to use his
method I'd have to start the interactive interpreter.

Bruno Desthuilliers wrote:
>
> Ivan Van Laningham a écrit :
> > Hi All--
> > The Python docs are not ideal. I can never remember, for instance,
> > where to find string methods (not methods in the string module, but
> > methods with ''),
>
> >>> dir('')

Metta,

Peter Hansen

unread,
May 11, 2005, 7:36:12 PM5/11/05
to
Christopher J. Bottaro wrote:
> Why can't Python have documentation like that? The language is
> awesome, it just needs documentation of the same quality.

The canonical answer is, roughly, 'it can'.

A standard addendum is to say that contributions are always welcome.

A common clarification of that is to point out that in open source
projects, somebody has to volunteer to do the work, or somebody has to
be willing to pay for it to be done. Which are you?

Personally, I have little problem with Python's docs, so I'm certainly
going to focus my negligible free time elsewhere. (Like rambling on and
on answering newsgroup postings. :-) If you felt strongly enough about
the negative aspects of Python's docs, you would be looking for places
where you could make a contribution. (Lack of experience is not only
not an excuse, but is probably an excellent qualification for the job!)

-Peter

Steven Bethard

unread,
May 11, 2005, 8:12:14 PM5/11/05
to
Ivan Van Laningham wrote:
> I should be able to type "string methods" into the text box,
> push submit, and IT SHOULD HAND ME THE PAGE. Not "Results 1 - 20 of
> about 9,800 from www.python.org for string methods. (0.78 seconds)"

Hmm... I typed in "string methods" at http://docs.python.org/ and got:

"""Results 1 - 10 of about 11 from docs.python.org for "string methods".
(0.06 seconds)"""

Without quoting, I got:

"""Results 1 - 10 of about 216 from docs.python.org for string methods.
(0.05 seconds)"""

In both cases, the right link was the first one. So I can't produce
your results.

Regardless, assuming the right link is the first one, do I understand
your complaint correctly as saying that you want Python to automatically
pick the first link for you? Do others agree with this complaint? I
imagine it wouldn't be that hard to add the equivalent of Google's "I'm
Feeling Lucky" button beside the submit button if that would really help.

> And the first hit is from Python 2.1.3, NOT the current doc.

Weird. I typed in "string methods" at http://docs.python.org/ and my
first hit was from the current Python docs. I get:

http://docs.python.org/lib/string-methods.html

In fact, I tried just "string" and couldn't find anything but the
current docs in the first 10 pages (and was too lazy to check anything
else).

Could you tell me how to reproduce your results (of getting Python 2.1.3)?

STeVe

Terry Reedy

unread,
May 11, 2005, 8:17:25 PM5/11/05
to pytho...@python.org

"Sébastien Boisgérault" <Sebastien....@gmail.com> wrote in message
news:1115841659....@o13g2000cwo.googlegroups.com...

>
> "Manual" == scope of the *Lib Reference* + informal style of the
> *Tutorial*,

You, as well as the OP, left out the Language Reference, which is the
manual (by me definition) for the language itself. Chapter 2 of the Lib
Reference on builtin types and functions is essential also and should be
read in its entirety. The rest, to me, is 'need to know' reading,
especially since the addition of string methods.

> Consider non-official manuals such as:
> + http://diveintopython.org/toc/index.html (free)
> + python in a nutshell
> + python cookbook
> + etc.

Yes, these and others (the etc) are helpful too, and should not be
discounted just because they are maintained independently of the core
developer group.

Terry J. Reedy

James Stroud

unread,
May 11, 2005, 8:22:29 PM5/11/05
to pytho...@python.org
Ivan and Company:

Keep this in your favorites bar:

http://rgruet.free.fr/PQR24/PQR2.4.html

Under "Contents", click on "Basic types and their operations:...string"

But I think this could have an expanded "idioms" section.
I.E.
for index,element in enumarate(alist):
or
for atup in zip(list1,list2):
Maybe we could compile a list? Maybe under "Idioms (was Re: Python Documentation)"?

Anybody care to send in their favorites? I'll compile them.

James

On Wednesday 11 May 2005 04:38 pm, Ivan Van Laningham wrote:
> Hi All--
> [rant]

--
James Stroud
UCLA-DOE Institute for Genomics and Proteomics
Box 951570
Los Angeles, CA 90095

http://www.jamesstroud.com/

John Bokma

unread,
May 11, 2005, 8:35:35 PM5/11/05
to
Ivan Van Laningham wrote:

> Python docs are not as good as PHP docs.

Oh my. I hope you are just making that up. PHP documentation is
guesstimated on how PHP works on average. Add the online comments clutter
and you probably are better off reading the source.

--
John MexIT: http://johnbokma.com/mexit/
personal page: http://johnbokma.com/
Experienced programmer available: http://castleamber.com/
Happy Customers: http://castleamber.com/testimonials.html

Ivan Van Laningham

unread,
May 11, 2005, 8:39:59 PM5/11/05
to Python Mailing List
Hi All--

Steven Bethard wrote:
>
> Ivan Van Laningham wrote:
> > I should be able to type "string methods" into the text box,
> > push submit, and IT SHOULD HAND ME THE PAGE. Not "Results 1 - 20 of
> > about 9,800 from www.python.org for string methods. (0.78 seconds)"
>

> Regardless, assuming the right link is the first one, do I understand
> your complaint correctly as saying that you want Python to automatically
> pick the first link for you? Do others agree with this complaint? I
> imagine it wouldn't be that hard to add the equivalent of Google's "I'm
> Feeling Lucky" button beside the submit button if that would really help.
>

No. If I type "string methods" into the search box (OK, I will type the
quotes), how many pages can there be? If there are two or more, give me
the choice; if there is one, take me to it. Why are there 9,801 pages
containing string, or method, or both, or neither? What's wrong with
this picture?

> http://docs.python.org/lib/string-methods.html
>
> In fact, I tried just "string" and couldn't find anything but the
> current docs in the first 10 pages (and was too lazy to check anything
> else).
>
> Could you tell me how to reproduce your results (of getting Python 2.1.3)?
>

http://www.python.org/doc/

Type string methods into the box; push submit. Result:

"Results 1 - 20 of about 9,800 from www.python.org for string methods.

(0.14 seconds)"

I did not go to docs.python.org, I went to www.python.org and clicked on
the doc link. There is a difference, clearly, but I maintain there
should not be. If I click on "Documentation" on the main page, am I
asking for "All possible old and new and broken and repaired and
intermediate documentation pages"? No, I kind of thought I was asking
for the latest documentation.

I tried string methods at docs.python.org, and got "Results 1 - 20 of
about 455 from docs.python.org for string methods. (0.11 seconds)";
"string methods" retrieved "Results 1 - 10 of about 30 from
docs.python.org for "string methods". (0.13 seconds)". Why the
difference?


Metta,
<i-have-not-yet-begun-to-rant>-ly y'rs,
Ivan "Sorry I am out of room for smiley faces"


----------------------------------------------
Ivan Van Laningham
God N Locomotive Works

http://www.pauahtun.org/

Robert Kern

unread,
May 11, 2005, 8:48:30 PM5/11/05
to pytho...@python.org
Ivan Van Laningham wrote:

> http://www.python.org/doc/
>
> Type string methods into the box; push submit. Result:
>

> "Results 1 - 20 of about 9,800 from www.python.org for string methods.

> (0.14 seconds)"
>
> I did not go to docs.python.org, I went to www.python.org and clicked on
> the doc link. There is a difference, clearly, but I maintain there
> should not be. If I click on "Documentation" on the main page, am I
> asking for "All possible old and new and broken and repaired and
> intermediate documentation pages"? No, I kind of thought I was asking
> for the latest documentation.
>
> I tried string methods at docs.python.org, and got "Results 1 - 20 of
> about 455 from docs.python.org for string methods. (0.11 seconds)";
> "string methods" retrieved "Results 1 - 10 of about 30 from
> docs.python.org for "string methods". (0.13 seconds)". Why the
> difference?

Searching on docs.python.org goes through just the stuff that's on
docs.python.org, which is pretty much just documentation. Google's magic
points to the current documentation.

Searching on www.python.org trolls through the entire www.python.org
site. The search box doesn't narrow its scope just because you happen to
be in the Documentation section currently. It doesn't get the current
documentation because Google's magic gets a bit confused.

--
Robert Kern
rk...@ucsd.edu

"In the fields of hell where the grass grows high
Are the graves of dreams allowed to die."
-- Richard Harter

Skip Montanaro

unread,
May 11, 2005, 9:41:30 PM5/11/05
to Christopher J. Bottaro, pytho...@python.org

Christopher> Exactly!! See thats what I'm saying. I _think_ its widely
Christopher> accepted that PHP has awesome documentation. And like rbt
Christopher> said, that makes it extremely useful. Why can't Python
Christopher> have documentation like that?

It's just a simple matter of writing, editing, proofreading, feedback, etc.
Given the current documentation set, does it appear what you're looking for
is mostly a reorganization of the existing content?

You gave the example of searching for "array". That happens to return
something very useful because it maps directly to a section of the PHP
manual. I tried searching for "float" and "string" but got much less
on-target responses. When I searched for a term and selected selected the
"online documentation" search category it did a Google search, which is what
the search box on docs.python.org does.

Skip

Skip Montanaro

unread,
May 11, 2005, 9:43:34 PM5/11/05
to Bruno Desthuilliers, pytho...@python.org
Ivan> I can never remember ...where to find string methods

>>>> dir('')
Bruno> ['__add__', '__class__', ...

Also:

>>> help(str)
Help on class str in module __builtin__:

class str(basestring)
| str(object) -> string
|
| Return a nice string representation of the object.
| If the argument is a string, the return value is the same object.
|

| Method resolution order:
| str
| basestring
| object
|
| Methods defined here:
...

Skip

Skip Montanaro

unread,
May 11, 2005, 9:46:00 PM5/11/05
to Steven Bethard, pytho...@python.org

Steve> [AMK's] wiki side-by-side with the Python docs:

Steve> http://pydoc.amk.ca/frame.html

There's also wikalong, though that's firefox-specific.

Skip

Terry Reedy

unread,
May 11, 2005, 10:08:21 PM5/11/05
to pytho...@python.org

"Christopher J. Bottaro" <cjbo...@alumni.cs.utexas.edu> wrote in message
news:d5tqi2$d8l$2...@sea.gmane.org...

> rbt wrote:
>> Because PHP is such a 'thrown together' and 'bolted-on' language. If it
>> didn't have *outstanding* documentation (which it does BTW), no one
>> could even begin to understand how they got from a little HTML language
>> to a kinda/sorta OO language.
>>
>> PHP is showing its age... thanks to its docs, it's still *extremely*
>> useful.
>
> Exactly!! See thats what I'm saying. I _think_ its widely accepted that
> PHP has awesome documentation. And like rbt said, that makes it
> extremely
> useful. Why can't Python have documentation like that? The language is

> awesome, it just needs documentation of the same quality.

Because of these two posts (and a few others) extolling the PHP
documentation, I decided to take a look for myself to see what the fuss was
about and whether I could get any ideas on how to improve Python's docs. I
typed "PHP manual" in my Google bar and the first link was just what I
hoped for, the PHP site manual.

First observation: the PHP manual is a combined 'kitchen-sink' volume that
combines material that Python separates: tutorial, language reference,
library reference, and doc for some 3rd party packages. Hmm, perhaps the 3
official volumes would be better integrated if combined into one manul with
three parts. But the difference itself between one volume with many parts
and many volume is not critical in itself.

Next, I picked the Array chapter in the Functions section. It starts with
a Unix man-style intro. Ok, but not 'awsome'. Next come the defined
constants, which don't mean much out of the context of the function where
used, so this part functions as an index of names. Then there is a long
alphabetical list of function name/links with a one-line description of
each. Gee, there seem to be a lot of different sort functions.

Finally, 80% of the chapter/page consists of a thrown-together mish-mash of
unsorted. unedited comments and questions. Some seem like the equivalent
of Python cookbook entries, but others are like run-of-the mill comp.lang
postings. So the Python equivalent of this 'document' would include the
Python Cookbook, the Python Wiki, and some of the c.l.p archives.

Onward to the page for sort(), which bizarrely (to me) rekeys the 'array'.
Then there is a cross-reference to the 9 other sort pages. Is there, I
wonder, anyplace where all 10 sort functions are discussed together? This
time, 90% of the page is user junk. Randomly clicking down, I find someone
complaining about sort dumping his keys, just as the top entry said (but
without the big warning box that such data destruction needs). Sorry, PHP
doc fans: to me, this sort of inflated, noisey bloatware is wretched, not
outstanding.

Conclusion 1: if PHP is anything as awful as the manual, it is not for me.

Conclusion 2: the somewhat spare style of the Python docs matches the
somewhat spare style of the language itself. (My goodness, only one list
sort method!). Since this style agrees with me, I would not want it to
change too much.

Conclusion 3: some people would apparently be happier with the Python docs
if they were combined into one Python Manual. This could be done as a
virtual anthology by writing a combined Table of Contents (with links) and
an Introduction discussing the various 'Parts' and their
interrelationships. It would not have to be limited to PSF material
either. I might even take a stab at it if I ever feel sufficiently
ambitious and energetic.

Terry J. Reedy

Paul Rubin

unread,
May 11, 2005, 10:52:23 PM5/11/05
to
hug...@gmail.com writes:
> I think Python's doc really rock. It's odd, why do you refer to the
> tutorial when the lib API is what I'd consider "the docs".

Some parts of the lib doc are better than others. The only way to
understand SocketServer, for example, is to read the long comment at
the beginning of the source file. I've been wanting to get around to
merging that with the doc writeup and adding some examples.

Tkinter, as well, is practically undocumented as far as the base distro
is concerned, but there's some good docs for it elsewhere on the web.

Paul Rubin

unread,
May 11, 2005, 10:53:29 PM5/11/05
to
"Sébastien Boisgérault" <Sebastien....@gmail.com> writes:
> "Manual" == scope of the *Lib Reference* + informal style of the
> *Tutorial*,

I don't care whether the style is formal or informal, the manual
should document the complete interface of the language and library and
right now it doesn't do anything like that.

Ivan Van Laningham

unread,
May 11, 2005, 11:43:01 PM5/11/05
to Python Mailing List
Hi All--

Robert Kern wrote:
>
> Ivan Van Laningham wrote:
>
> > http://www.python.org/doc/
> >

> Searching on docs.python.org goes through just the stuff that's on
> docs.python.org, which is pretty much just documentation. Google's magic
> points to the current documentation.
>
> Searching on www.python.org trolls through the entire www.python.org
> site. The search box doesn't narrow its scope just because you happen to
> be in the Documentation section currently. It doesn't get the current
> documentation because Google's magic gets a bit confused.
>

I get that. My question, cleverly concealed in a rant, was, "Why does
clicking on the Documentation link at python.org NOT take me to
docs.python.org?" Why is there a difference? If there must be a
difference, why isn't the difference labelled as such? This is a
difference that makes a difference.

Metta,
Ivan
----------------------------------------------
Ivan Van Laningham
God N Locomotive Works

http://www.pauahtun.org/

Ivan Van Laningham

unread,
May 11, 2005, 11:46:09 PM5/11/05
to Python Mailing List
Hi All--

John Bokma wrote:
>
> Ivan Van Laningham wrote:
>
> > Python docs are not as good as PHP docs.
>
> Oh my. I hope you are just making that up. PHP documentation is
> guesstimated on how PHP works on average. Add the online comments clutter
> and you probably are better off reading the source.
>

I didn't write that; I was riffing on Christopher's contention that
Python's docs ought to be awesome, which I think ought to be true.

Robert Kern

unread,
May 11, 2005, 11:51:15 PM5/11/05
to pytho...@python.org
Ivan Van Laningham wrote:
> Hi All--
>
> Robert Kern wrote:
>
>>Ivan Van Laningham wrote:
>>
>>
>>>http://www.python.org/doc/
>>>
>>
>>Searching on docs.python.org goes through just the stuff that's on
>>docs.python.org, which is pretty much just documentation. Google's magic
>>points to the current documentation.
>>
>>Searching on www.python.org trolls through the entire www.python.org
>>site. The search box doesn't narrow its scope just because you happen to
>>be in the Documentation section currently. It doesn't get the current
>>documentation because Google's magic gets a bit confused.
>
> I get that. My question, cleverly concealed in a rant, was, "Why does
> clicking on the Documentation link at python.org NOT take me to
> docs.python.org?" Why is there a difference? If there must be a
> difference, why isn't the difference labelled as such? This is a
> difference that makes a difference.

I believe that docs.python.org was added mostly to aid Google searches.
I *do* think that the Documentation link should go to docs.python.org. I
believe there is a mailing list somewhere that discusses improvements to
the website.

<Googles> Ah:

http://mail.python.org/mailman/listinfo/pydotorg/

Ivan Van Laningham

unread,
May 11, 2005, 11:54:09 PM5/11/05
to Python Mailing List
Hi All--

Terry Reedy wrote:
>
> Conclusion 3: some people would apparently be happier with the Python docs
> if they were combined into one Python Manual. This could be done as a
> virtual anthology by writing a combined Table of Contents (with links) and
> an Introduction discussing the various 'Parts' and their
> interrelationships. It would not have to be limited to PSF material
> either. I might even take a stab at it if I ever feel sufficiently
> ambitious and energetic.
>

There are a GREAT many brilliant minds on this list, many of them
excellent writers (certain noisy parties excepted). I write, and I am
certainly offering to help, but I think what's needed here is someone
who can organize better than the average person. Terry might have the
right idea; maybe all that is needed is a hot table of contents,
although a few other repairs are in order, such as making the
Documentation link on the python.org front page point to the right
place.

A documentation Tips page wouldn't hurt, either; all these handy little
tricks people have been offering for my string methods problem ought to
be on a highly visible page. No, not a 'How to find "string methods"'
page, but "Tips & Tricks for Interrogating the Python Docs" page.

Aahz

unread,
May 12, 2005, 12:45:38 AM5/12/05
to
In article <mailman.425.11158699...@python.org>,

Robert Kern <rk...@ucsd.edu> wrote:
>
>I believe that docs.python.org was added mostly to aid Google searches.
>I *do* think that the Documentation link should go to docs.python.org. I
>believe there is a mailing list somewhere that discusses improvements to
>the website.
>
><Googles> Ah:
>
>http://mail.python.org/mailman/listinfo/pydotorg/

Google gave you the wrong answer. ;-) pydotorg is for people actively
working on the website, not for discussions about improving the website.
There's another list for that, but it's currently moribund because we're
waiting for a website redesign. (The PSF board voted to pay someone to
redesign www.python.org.)
--
Aahz (aa...@pythoncraft.com) <*> http://www.pythoncraft.com/

"And if that makes me an elitist...I couldn't be happier." --JMS

Steven Bethard

unread,
May 12, 2005, 12:45:50 AM5/12/05
to
Ivan Van Laningham wrote:
> I get that. My question, cleverly concealed in a rant, was, "Why does
> clicking on the Documentation link at python.org NOT take me to
> docs.python.org?"

I believe the issue here is that docs.python.org is only the *current*
documentation. www.python.org/doc lists a variety of items which are
not part of the current documentation, e.g.:

* the development documentation
* documentation for previous python versions
* the Python wiki
etc.

None of these are part of the official current documentation, so they're
not on docs.python.org (so that when you search docs.python.org, you
*do* only get the current documentation).

Would it have been better for you if the large link that says
"Browse Current Documentation"
said instead
"Browse and Search Current Documentation"
?

STeVe

Terry Hancock

unread,
May 12, 2005, 1:11:12 AM5/12/05
to pytho...@python.org
On Wednesday 11 May 2005 02:54 pm, Christopher J. Bottaro wrote:
> 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).

That's probably because

1) The language itself is extremely simple. What you really need is in the
tutorial (or in several books including "Learning Python" from O'Reilly which
I learned from). If you need more than that, then you must be looking for
something fairly picky (like "magic methods" perhaps), so you really do want
to be reading the "Language Reference". Don't overthink it.

2) About 90% of what you want to do in Python is done by using a library
module. Furthermore, it's the 90% you are likely to forget, thus needing
a manual for reference. That's why I regard the "Library Reference" as
"the manual". Don't forget that many "built-ins" are documented here as
well (e.g. the methods of strings*).

There are, of course, numerous introductions to Python which can be freely
downloaded, and several commercial books on the subject. IMHO, the
"manual" is to be the ultimate, most up-to-date, most accurate, and most
detailed source on the language (you go there to check details if something
doesn't work the way your tutorial says it does). Readability is secondary ---
use a third party source for the "friendly" version (not that the Language
or Library References are unfriendly --- they're just concise, IMHO).

Also, Python gives you something most languages don't --- the interactive
interpreter allows you to play around with Python constructs and find out
how any picky details work by trying it out. This is clearly the most
guaranteed accurate way to find out the answer to a syntax or semantic
problem, and it's so easy it's hard to justify the wasted time perusing a
manual for such details. That's why people are frequently recommended
to "ask the interpreter" about such details. This saves a HUGE amount
of time for me --- I'm surprised that you dislike this approach, it seems
extremely practical to me.

*But you do have to remember that strings are documented under "sequences"
this is probably my biggest complaint about the Library Reference --- something
as important as string methods should have its own heading in the top-level
outline. But that's a nitpick, of course.

--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks http://www.anansispaceworks.com

Terry Hancock

unread,
May 12, 2005, 1:13:37 AM5/12/05
to pytho...@python.org
On Wednesday 11 May 2005 03:42 pm, flamesrock wrote:
> I don't know what you guys are talking about!!
> In idle:
> help(module)
>
> I love the way python handles documentation. Its not invansive

Yeah, and if you write your docstrings with reasonable care it
works for your own modules, too! I love that.

ISTM, that Python is the best "Literate Programming" language
yet available (much easier than cweb and whatnot that gave
us the term).

Robert Kern

unread,
May 12, 2005, 1:02:48 AM5/12/05
to pytho...@python.org
Aahz wrote:
> In article <mailman.425.11158699...@python.org>,
> Robert Kern <rk...@ucsd.edu> wrote:
>
>>I believe that docs.python.org was added mostly to aid Google searches.
>>I *do* think that the Documentation link should go to docs.python.org. I
>>believe there is a mailing list somewhere that discusses improvements to
>>the website.
>>
>><Googles> Ah:
>>
>>http://mail.python.org/mailman/listinfo/pydotorg/
>
> Google gave you the wrong answer. ;-) pydotorg is for people actively
> working on the website, not for discussions about improving the website.
> There's another list for that, but it's currently moribund because we're
> waiting for a website redesign. (The PSF board voted to pay someone to
> redesign www.python.org.)

Dammit! Google's supposed to read my mind and give me what I want, not
what I ask for!

John Bokma

unread,
May 12, 2005, 2:19:24 AM5/12/05
to
Ivan Van Laningham wrote:

> Hi All--
>
> John Bokma wrote:
>>
>> Ivan Van Laningham wrote:
>>
>> > Python docs are not as good as PHP docs.
>>
>> Oh my. I hope you are just making that up. PHP documentation is
>> guesstimated on how PHP works on average. Add the online comments
>> clutter and you probably are better off reading the source.
>>
>
> I didn't write that; I was riffing on Christopher's contention that
> Python's docs ought to be awesome, which I think ought to be true.

Apologies for the misquoting :-) I couldn't even imagine that the statement
could be true in anyway. I've read the introduction, and Dive into Python,
which I highly recommend, and I liked what I read :-).

Roel Schroeven

unread,
May 12, 2005, 4:11:40 AM5/12/05
to
Terry Reedy wrote:

> Because of these two posts (and a few others) extolling the PHP
> documentation, I decided to take a look for myself to see what the
> fuss was about and whether I could get any ideas on how to improve
> Python's docs.
>

> [...]


>
> Finally, 80% of the chapter/page consists of a thrown-together
> mish-mash of unsorted. unedited comments and questions.

In my experience, the user comments in many cases are almost useless.
Sometimes just confusing, sometimes contradicting each other, sometimes
even incorrect. Sometimes correct and useful too, but IMO that gets
drown between all the others.

> [...]


> Sorry, PHP doc fans: to me, this sort of inflated, noisey bloatware
> is wretched, not outstanding.

Thank you. I thought I was the only one in the world who doesn't like
the PHP documentation.

> Conclusion 1: if PHP is anything as awful as the manual, it is not
> for me.

I'm fairly sure you won't like PHP :)

Some time ago I used to do some programming in PHP on the side. In the
beginning, I thought PHP was quite a nice language. I even used it to
write some small non-web programs that I would otherwise haven written
in C or C++ (I didn't know Python at the time, nor any other decent
scripting language(*) ).
Then I discovered Python, which caused my dislike of PHP to grow even
more. PHP tries to make everything as simple as possible but that
doesn't always work out very well, as explained in the section
'Oversimplification Leading to Excessive Complexity' of this paper:
http://www.ukuug.org/events/linux2002/papers/html/php/#section_5.
Python OTOH makes things as simple as possible but not any simpler, and
that turns out to work much better.

(Disclaimer: I haven't done any web programming in the meantime, so I
don't know from own experience how Python fares in that area. But I'm
fairly confident that it would work out just nice.)


(Sorry for this off-topic rant)

(*) I know Python is not just a scripting language, but the things I
used PHP for at the time really were nothing more than scripts, despite
me thinking about writing them in C or C++.

--
If I have been able to see further, it was only because I stood
on the shoulders of giants. -- Isaac Newton

Roel Schroeven

Fredrik Lundh

unread,
May 12, 2005, 6:30:39 AM5/12/05
to pytho...@python.org
Terry Reedy wrote:

> Conclusion 1: if PHP is anything as awful as the manual, it is not for me.

the whole idea that turning the manual into a wiki or a forum will solve all
problems is extremely naive.

on the other hand, having written lots of "manual enhancing material", I would
love to be able to add links to the library manual in some non-intrusive way
(similar to blog trackbacks). what you need is a way to uniquely identify a
library construct (e.g. a psuedo-URL or simply a dotted path), a way to
contribute a path/link collection, and an addition to the HTML generation
toolchain that adds relevant links to the generated HTML. e.g.

<annotations src="http://effbot.org/python-annotations.xml">
<example>
<title>Building An Asynchronous FTP Client</title>
<target>asynchat.async_chat</target>
<href>http://effbot.org/zone/asyncore-ftp-client.htm</href>
</example>
<example>
<title>The select module</title>
<target>select.select</target>
<href>http://effbot.org/librarybook/select.htm</href>
</example>
<example>
<title>Using the tempfile module to open temporary files</title>
<target>tempfile</target>
<target>tempfile.TemporaryFile</target>
<href>http://effbot.org/librarybook/tempfile.htm#tempfile-example-2</href>
</example>
<example>
<title>Importing Python Modules</title>
<target>statement:import</target>
<target>statement:from</target>
<href>http://effbot.org/zone/import-confusion.htm</href>
</example>
</annotation>

(I'm sure some RDF hacker can come up with an unreadable alternative
to this, if necessary ;-)

this eliminates the need for constant monitoring of wiki pages and forums, and
reduces the workload for the documentation editors compared to all the "feel
free to contribute patches" alternatives. if some annotation provider produces
bad stuff or spam, remove his/her annotations, or use a whitelist/blacklist on
individual items.

if someone fixes the python.org end of things, I can generate an effbot.org
annotation index within a day or two.

</F>

Fredrik Lundh

unread,
May 12, 2005, 6:49:22 AM5/12/05
to pytho...@python.org
> toolchain that adds relevant links to the generated HTML. e.g.

oops. here's the pre-paste-and-cut-error text:

toolchain that adds relevant links to the generated HTML. with that
in place, external contributors can then place an annotation file on their
own server, and send the link to the editors. e.g.

</F>

James Carroll

unread,
May 12, 2005, 9:09:26 AM5/12/05
to Fredrik Lundh, pytho...@python.org
>
> > Conclusion 1: if PHP is anything as awful as the manual, it is not for me.
>
> the whole idea that turning the manual into a wiki or a forum will solve all
> problems is extremely naive.
>

Wha?

I haven't done PHP for a couple of years, but when I really needed
documentation, the PHP docs were well organized, and told me exactly
what I needed, and when I didn't find it in the official part of the
docs, invariably someone had run into the same problem I had and
posted the solution at the end of the docs page. It really is great
when you are actually doing PHP and it's your main resource. Even if
you're just critisizing something that you're vaguely familliar with,
for the fun of it, you're not actually critisizing it as much as
calling it poo poo without any real world examples of why it "is
extremely naive" or what would work better...

One of the things I like about the python list is that it generally
has a high signal to noise ratio, but this is just noise...

-Jim

Skip Montanaro

unread,
May 12, 2005, 9:48:43 AM5/12/05
to Paul Rubin, pytho...@python.org

Paul> Some parts of the lib doc are better than others. The only way to
Paul> understand SocketServer, for example, is to read the long comment
Paul> at the beginning of the source file. I've been wanting to get
Paul> around to merging that with the doc writeup and adding some
Paul> examples.

Thanks for the suggestion. I just incorporated the module doc string into
the SocketServer doc (CVS HEAD and 2.4 release branch).

Paul> Tkinter, as well, is practically undocumented as far as the base
Paul> distro is concerned, but there's some good docs for it elsewhere
Paul> on the web.

I'll let someone else tackle that one. ;-)

Skip

Skip Montanaro

unread,
May 12, 2005, 9:57:08 AM5/12/05
to Ivan Van Laningham, Python Mailing List

Ivan> I get that. My question, cleverly concealed in a rant, was, "Why
Ivan> does clicking on the Documentation link at python.org NOT take me
Ivan> to docs.python.org?"

I almost changed that link, but then reconsidered. Compare

http://docs.python.org/

with

http://www.python.org/docs/

The former is just the main documentation that's part of the Python
distribution. The latter contains links to lots of supplementary material,
much of which is not part of python.org.

The original functional goal of the http://docs.python.org/ URL was to
provide a cleaner isolation of "just the facts, Ma'am" so that Google could
do a better job presenting documentation search results. Previously, it was
impossible to separate the mailing list archives from the documentation
proper in Google searches.

Skip

Terry Hancock

unread,
May 12, 2005, 11:23:34 AM5/12/05
to Python Mailing List
On Thursday 12 May 2005 08:57 am, Skip Montanaro wrote:
> Ivan> I get that. My question, cleverly concealed in a rant, was, "Why
> Ivan> does clicking on the Documentation link at python.org NOT take me
> Ivan> to docs.python.org?"
> I almost changed that link, but then reconsidered. Compare
> http://docs.python.org/
> with
> http://www.python.org/docs/
[...]

> The original functional goal of the http://docs.python.org/ URL was to
> provide a cleaner isolation of "just the facts, Ma'am" so that Google could
> do a better job presenting documentation search results. Previously, it was
> impossible to separate the mailing list archives from the documentation
> proper in Google searches.

Maybe a good compromise would be to have a search form on the
http://www.python.org/doc/ page labeled "Search Documentation"
which did a search on http://docs.python.org/ , then?

Though I see that "Browse Documentation" does indeed go to
http://docs.python.org .

Cheers,
Terry

Christopher J. Bottaro

unread,
May 12, 2005, 11:20:45 AM5/12/05
to pytho...@python.org
Steven Bethard wrote:

> Ivan Van Laningham wrote:
>> The Python docs are not ideal. I can never remember, for instance,
>> where to find string methods (not methods in the string module, but
>> methods with '')
>
> Hmmm... Well going to http://docs.python.org/ and typing "string
> methods" into the search box gives, as the first hit:
>
> http://docs.python.org/lib/string-methods.html
>
> Even if you just search for "string", that URL is the second hit, and
> pretty clearly the right one from the title.
>
> STeVe

Heh, searching "dict methods" didn't produce the correct results on the
first page. "dictionary methods" did. searching for "append" returned the
array's module page as the first result, and list's module page as the 8th
result. Search for "static" came up with nothing. Search for
"staticmethod" came up with the built-in-funcs page, from which I had to
search again for "staticmethod".

The search mechanism isn't all that great (imo anyways). Honestly, neither
is the PHP one, except when you are only searching the function list. Then
its the bomb. I also like how each PHP function gets its own page and each
page is full of examples. And I love how each page shows related
functions. Granted its easier to do the function list search for PHP
because there are no namespaces or classes, but still I think Python could
do something similar. Say for instance search for "append" and it will
come back with a page for list's append, a page for array's append, etc.

My idea for a manual's table of contents:

1. Variables
2. Conditional and Branching Constructs
3. Looping Constructs
4. Functions
5. Modules
6. Classes
7. Exceptions
8. Built-in
8.1 Functions
8.2 Types

Of course there should be more detailed sublevels. The tutorial (at least
chapters 3-11) make a good (partial) manual. I think those chapters should
be the basis for a real manual vs. a tutorial.

If I wanted to learn about "types" in Python, where do I look? The PHP
manual has a whole section on the built-in types, how to get the type of a
var, how to change cast the type of a var, etc. I think that is such an
important and basic part of any language, yet its scattered all over Python
documention, difficult to find (i.e. not in a manual, but the library
reference).

I guess what I'm trying to say is that there should be a "manual" which is
half way between the tutorial and the library reference, that is organized
more like a traditional manual (whatever that means, right?) and is more
easily searchable.

-- C

Christopher J. Bottaro

unread,
May 12, 2005, 11:26:00 AM5/12/05
to pytho...@python.org
Steven Bethard wrote:

> Christopher J. Bottaro wrote:
>> Contrast that with Python. First off there is no "search" mechanism
>> built into the documentation page (yes I know you can google it, but that
>> just doesn't feel right).
>
> Um, are you looking at the current documentation page?
>
> http://docs.python.org/
>
> In the upper right hand corner, I see a box entitled "Search:" and a
> button that says "submit".

Oops. I link directly to the tutorial and library reference...=)

> STeVe

-- C

Tim Williams

unread,
May 12, 2005, 11:42:34 AM5/12/05