Python docs disappointing

[kj]

I'm pretty new to Python, and I like a lot overall, but I find the
documentation for Python rather poor, overall.

I'm sure that Python experts don't have this problem: they have
internalized some good ways to access the documentation, are
productive with it, and therefore have lost the ability to see why
the Python documentations is deficient for beginners. This explains
why a suboptimal situation can persist like this: those who are
most able fix it are also the least able to perceive it.

I've heard similar complaints from other experienced programmers
who are trying out Python for the first time: poor documentation.

Here is an *entirely typical* example: on some Unix, try

% pydoc urllib

The displayed documentation mention the optional parameter "data"
in practically every function listed (a few dozen of them). This
parameter is not documented *anywhere* on that page. All that we
are told is that its default value is always None.

I'm sure that I can find a full description of this parameter if
I fire up Google, and search online. In fact, more likely than
not, I'll find far more documentation than I want. But my point
is that a programmer should not need to do this. The full
documentation should be readily accessible directly through a few
keystrokes.

I would love to know how experienced Python programmers quickly
zero in on the Python documentation they need.

TIA!

kynn

 

[Robert Kern]

I would love to know how experienced Python programmers quickly
zero in on the Python documentation they need.

http://docs.python.org/library/urllib

I use Firefox's "Quick Searches" feature to make getting this URL as fast as
possible:

"m urllib"

--
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth."
-- Umberto Eco

 

[r]

I'm pretty new to Python, and I like a lot overall, but I find the
documentation for Python rather poor, overall.

[snip]

If you mean the built-in docs i *highly agree* with you. if you mean
docs/tutorials available across the WWW i *highly disagree* with you,
and if you mean the command line "help" i also *highly disagree*, of
which python has the-best-in the-world!

I am using 2.6.2 and the help docs are a joke. trying to find even the
simplest thing (built-in functions, etc...) is like pulling teeth. I
do not look at them anymore, or do i plan to in the future. Luckily i
know python pretty well, but i can't image the horrors a new Python
Programmer must face now...

Kj, you could not be more right. Doc maintainers need to get some
feedback from Python noobies when writing this stuff. Does anybody
remember CP4E? I know Guido put a lot of effort into this project and
very much believed in this philosophy(circa 1999~2005), although it
never really went very far, i still believe in Guido's heart the CP4E
exists -- if only barley clinging to life(...maybe?)

any thoughts on this Pythonistas?

 

[Emmanuel Surleau]

I'm pretty new to Python, and I like a lot overall, but I find the
documentation for Python rather poor, overall.

I'm sure that Python experts don't have this problem: they have
internalized some good ways to access the documentation, are
productive with it, and therefore have lost the ability to see why
the Python documentations is deficient for beginners. This explains
why a suboptimal situation can persist like this: those who are
most able fix it are also the least able to perceive it.

I've heard similar complaints from other experienced programmers
who are trying out Python for the first time: poor documentation.

The documentation on python.org is quite extensive. In particular, you may
want to look at the PEPs, which offer fascinating insights for the reasoning
behind particular features of Python.

Here is an *entirely typical* example: on some Unix, try

% pydoc urllib

The displayed documentation mention the optional parameter "data"
in practically every function listed (a few dozen of them). This
parameter is not documented *anywhere* on that page. All that we
are told is that its default value is always None.

I'm sure that I can find a full description of this parameter if
I fire up Google, and search online. In fact, more likely than
not, I'll find far more documentation than I want. But my point
is that a programmer should not need to do this. The full
documentation should be readily accessible directly through a few
keystrokes.

You have first-grade documentation on the Python website:
http://docs.python.org/library/urllib.html
I'm not really using pydoc, but I'd wager it's more used as a quick lookup
than anything else.

I would love to know how experienced Python programmers quickly
zero in on the Python documentation they need.

I wouldn't count myself as an 'experienced' Python programmer, but I rely on
docs.python.org for most things with regards to the standard library.

Cheers,

Emm

 

[Carl Banks]

I'm pretty new to Python, and I like a lot overall, but I find the
documentation for Python rather poor, overall.

I'm sure that Python experts don't have this problem: they have
internalized some good ways to access the documentation, are
productive with it, and therefore have lost the ability to see why
the Python documentations is deficient for beginners.

That may be so, but I do remember when I was a beginner myself and I
had no issue with the documentation.


[snip]

I'm sure that I can find a full description of this parameter if
I fire up Google, and search online.

Are you aware that Python ships with a full set of documentation,
where (for instance) the meaning of "data" in urllib is defined? You
don't need Google.

In fact, more likely than
not, I'll find far more documentation than I want.  But my point
is that a programmer should not need to do this.  The full
documentation should be readily accessible directly through a few
keystrokes.

Well, no one volunteered to do that. Oh well.

I would love to know how experienced Python programmers quickly
zero in on the Python documentation they need.

Choose bookmark in web browser for Python documentation -> keyword
search for correct module (easy with firefox) -> scroll.

This might not be the smoothest method ever (omg you have to use a
*mouse*) but it should be usable enough.


Carl Banks

 

[Masklinn]

You have first-grade documentation on the Python website:
http://docs.python.org/library/urllib.html
I'm not really using pydoc, but I'd wager it's more used as a quick
lookup
than anything else.

Another important documentary resource for the stdlib is Doug
Hellmann's awesome Python Module of the Day series (http://www.doughellmann.com/PyMOTW/
)

 

[Carl Banks]

Apart from that what have the Pythonistas ever done for us? Nothing!

Please don't feed the trolls.

And if you do feed the trolls don't smile at them.


Carl Banks

 

[kj]

(omg you have to use a
*mouse*)

That's precisely the point. There's a huge number of programmers
out there who, like me, *hate* to use the mouse while they're
coding. It is truly disappointing to us that the developers of
Python chose to completely disregard this constituency.

This is one area in which Perl still whips Python...

kynn

 

[r]

That may be so, but I do remember when I was a beginner myself and I
had no issue with the documentation.

have you tried the new docs (>= 2.6) The interface has changed
drastically as to render itself completely useless. The old docs (<=
2.5) --the ones i learned from-- where flawless.


@ Mark Lawrence
Have you clicked any of those links? try the "Tutorial start here" and
then try to find a menu of sorts. It seems you have to click "next" to
navigate. Thats pretty counter intuitive if you need to get to page
589!! Upon clicking the tutorial link in the OLD DOCS, you where
presented with a nice menu for concise navigation.

 

[Mark Lawrence]

have you tried the new docs (>= 2.6) The interface has changed
drastically as to render itself completely useless. The old docs (<=
2.5) --the ones i learned from-- where flawless.


@ Mark Lawrence
Have you clicked any of those links? try the "Tutorial start here" and
then try to find a menu of sorts. It seems you have to click "next" to
navigate. Thats pretty counter intuitive if you need to get to page
589!! Upon clicking the tutorial link in the OLD DOCS, you where
presented with a nice menu for concise navigation.

Yes. Works perfectly as evidenced by the fact that this evening I've
checked data on the cProfile, pstats and array modules.

 

[Carl Banks]

That's precisely the point.  There's a huge number of programmers
out there who, like me, *hate* to use the mouse while they're
coding.

You would have figured one of them would have written a script or
something if there were so many. Maybe check the Python Cookbook for
someone's pet trick, I bet there is one or two there. Or figure out a
way to use elinks, the text mode web browser. You know, text mode
browsers have come a long way since the lynx days.

 It is truly disappointing to us that the developers of
Python chose to completely disregard this constituency.

Python is a volunteer effort, chief.

If all these programmers have this itch, as you claim, they've all
disregarded themselves by failing to contribute something.

This is one area in which Perl still whips Python...

No way. Perl's man pages are organized so poorly there is no
ergonomic pit deep enough to offset them. Quick, what man page is the
"do" statement documented in?


Carl Banks

 

[kj]

In <[email protected]>

<snip>

Thanks. Your remarks at least confirm that my impression was not
simply due to my noob ignorance: the keyboard-accessible docs are
indeed as poor as they look.

kynn

 

[Nikolaus Rath]

No way. Perl's man pages are organized so poorly there is no
ergonomic pit deep enough to offset them. Quick, what man page is the
"do" statement documented in?

Of course there is:

$ perldoc -f do | head
do BLOCK
Not really a function. Returns the value of the last command
in the sequence of commands indicated by BLOCK. When modified
by the "while" or "until" loop modifier, executes the BLOCK
once before testing the loop condition. (On other statements
the loop modifiers test the conditional first.)

"do BLOCK" does not count as a loop, so the loop control
statements "next", "last", or "redo" cannot be used to leave or
restart the block. See perlsyn for alternative strategies.
$


Best,

-Nikolaus

 

[Chris Jones]

You would have figured one of them would have written a script or
something if there were so many. Maybe check the Python Cookbook for
someone's pet trick, I bet there is one or two there. Or figure out a
way to use elinks, the text mode web browser. You know, text mode
browsers have come a long way since the lynx days.

So true.. I would add that one of the unplanned merits of a well-thought
out text mode browser such as ELinks is to remove all the fluff and
leave you, the reader, face to face with the site's content - or lack
thereof.

CJ

 

[Carl Banks]

In <[email protected]>


<snip>

Thanks.  Your remarks at least confirm that my impression was not
simply due to my noob ignorance: the keyboard-accessible docs are
indeed as poor as they look.

In the standard library, docstrings (which is what pydoc prints) are
intended to be a brief explanation/reminder of usage, not an
exhaustive description. Where docstrings are present, they are more
or less adequate for their intended use (although the quality of
docstrings does vary highly throughout the library).

If you are trying to use pydoc in a way not intended, then yes you
would likely find that they are poor when used in that unintended way.

Docstrings take up memory in a running process, so they are not ever
likely to be converted to an exhaustive description. Your best bet is
to figure out a way to automate lookup in the html documentation.


Carl Banks

 

[r]

Yes.  Works perfectly as evidenced by the fact that this evening I've
checked data on the cProfile, pstats and array modules.

Hold the phone... You checked data on modules using the "Tutorial
Start Here" link? Would not the "Global Module Index" be more, shall
we say, "informative"?

 

[Kee Nethery]

I too find the Python docs not very useful and it really slows down my
learning curve.

I wonder if it would make sense to find good tech writers, get a
quotes, and get some professionally written documentation WITH LOTS OF
EXAMPLES added to the standard Python documentation tree.

I'd chip in money for that task. I've certainly spent enough buying
Python books to where it would be very reasonable to chip in the cost
of one book towards this project. Get enough people ... could be a
great thing.

Even though it is not the version I use, I would suggest that the
really detailed docs with lots of examples be written against the
latest python version.

Just a thought.

Kee Nethery

 

[Mark Lawrence]

Hold the phone... You checked data on modules using the "Tutorial
Start Here" link? Would not the "Global Module Index" be more, shall
we say, "informative"?

You asked "Have you clicked any of those links?". I answered yes since
they all work. I usually navigate to module data via the index tab as I
find this the easiest way. I'm sure other people prefer the global
module index. Six of one, half a dozen of the other?

 

[Aahz]

That's precisely the point. There's a huge number of programmers out
there who, like me, *hate* to use the mouse while they're coding. It
is truly disappointing to us that the developers of Python chose to
completely disregard this constituency.

That's why I use Lynx on a local copy of the Python docs. Next question?
--
Aahz ([email protected]) <*> http://www.pythoncraft.com/

"Many customs in this life persist because they ease friction and promote
productivity as a result of universal agreement, and whether they are
precisely the optimal choices is much less important." --Henry Spencer

 

[Steven D'Aprano]

In <e22013d0-fbad-44e0-919b-ad5bb5f2ddb4@g19g2000vbi.googlegroups.com>


That's precisely the point. There's a huge number of programmers out
there who, like me, *hate* to use the mouse while they're coding.

Complain to the developers of your web browser then. Or use a different
web browser.

It is
truly disappointing to us that the developers of Python chose to
completely disregard this constituency.

Python is open source software developed by a community of volunteers, so
*you* are one of the developers of Python. You have an itch that needs
scratching. Solve it yourself, and release it to the wider community,
don't expect somebody else to do so.

Nobody is entitled to any functionality in Python. You can ask for it
nicely, and if somebody thinks it's a good idea, and have nothing better
to do, they may code it out of the goodness of their heart. Or you can do
it yourself, or you can pay somebody to do it if you don't have the
technical skill yourself. Or you can do without.

This is one area in which Perl still whips Python...

If so, it's because Perl has more people who understand that the way to
get something done is to do it, rather than whining about it.