Python docs disappointing

135 views
Skip to first unread message

kj

unread,
Jul 31, 2009, 4:10:45 PM7/31/09
to


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

unread,
Jul 31, 2009, 4:28:01 PM7/31/09
to pytho...@python.org
On 2009-07-31 15:10, kj wrote:

> 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

unread,
Jul 31, 2009, 4:29:36 PM7/31/09
to
On Jul 31, 3:10 pm, kj <no.em...@please.post> wrote:
> 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

unread,
Jul 31, 2009, 4:34:06 PM7/31/09
to pytho...@python.org
On Friday 31 July 2009 22:10:45 kj wrote:
> 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

Mark Lawrence

unread,
Jul 31, 2009, 4:55:35 PM7/31/09
to pytho...@python.org

I entirely agree with these comments. Looking at home on the compiled
help file on windows for python 2.6.2 I can't see anything except for
some icons at the top, the Contents, Index, Search and Favorites tabs on
the left and the following on the right.

What's new in Python 2.6? or all "What's new" documents since 2.0
Tutorial start here
Using Python how to use Python on different platforms
Language Reference describes syntax and language elements
Library Reference keep this under your pillow
Python HOWTOs in-depth documents on specific topics
Extending and Embedding tutorial for C/C++ programmers
Python/C API reference for C/C++ programmers
Installing Python Modules information for installers & sys-admins
Distributing Python Modules sharing modules with others
Documenting Python guide for documentation authors
Indices and tables:
Global Module Index quick access to all modules
General Index all functions, classes, terms
Glossary the most important terms explained
Search page search this documentation
Complete Table of Contents lists all sections and subsections
Meta information:
Reporting bugs
About the documentation History and License of Python
Copyright

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

--
Kindest regards.

Mark Lawrence.

Carl Banks

unread,
Jul 31, 2009, 5:16:48 PM7/31/09
to
On Jul 31, 1:10 pm, kj <no.em...@please.post> wrote:
> 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

unread,
Jul 31, 2009, 5:19:07 PM7/31/09
to pytho...@python.org
On 31 Jul 2009, at 22:34 , Emmanuel Surleau wrote:
> 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

unread,
Jul 31, 2009, 5:23:02 PM7/31/09
to
On Jul 31, 1:55 pm, Mark Lawrence <breamore...@yahoo.co.uk> wrote:
> 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

unread,
Jul 31, 2009, 5:28:36 PM7/31/09
to

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

unread,
Jul 31, 2009, 5:30:47 PM7/31/09
to
On Jul 31, 4:16 pm, Carl Banks <pavlovevide...@gmail.com> wrote:
> On Jul 31, 1:10 pm, kj <no.em...@please.post> wrote:
>
> > 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.

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

unread,
Jul 31, 2009, 5:53:02 PM7/31/09
to pytho...@python.org

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

Carl Banks

unread,
Jul 31, 2009, 6:03:25 PM7/31/09
to
On Jul 31, 2:28 pm, kj <no.em...@please.post> wrote:

> In <e22013d0-fbad-44e0-919b-ad5bb5f2d...@g19g2000vbi.googlegroups.com> Carl Banks <pavlovevide...@gmail.com> writes:
>
> >(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.

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

unread,
Jul 31, 2009, 6:09:42 PM7/31/09
to
In <09bf4f17-40a5-4bad...@g6g2000vbr.googlegroups.com>
Carl Banks <pavlove...@gmail.com> writes:

<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

unread,
Jul 31, 2009, 6:38:25 PM7/31/09
to
Carl Banks <pavlove...@gmail.com> writes:
>> 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?

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

--
»Time flies like an arrow, fruit flies like a Banana.«

PGP fingerprint: 5B93 61F8 4EA2 E279 ABF6 02CF A9AD B7F8 AE4E 425C

Carl Banks

unread,
Jul 31, 2009, 6:55:19 PM7/31/09
to
On Jul 31, 3:09 pm, kj <no.em...@please.post> wrote:
> In <09bf4f17-40a5-4bad-81d3-1950545b7...@g6g2000vbr.googlegroups.com>

>
> Carl Banks <pavlovevide...@gmail.com> writes:
>
> <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

Chris Jones

unread,
Jul 31, 2009, 6:54:52 PM7/31/09
to pytho...@python.org
On Fri, Jul 31, 2009 at 06:03:25PM EDT, Carl Banks wrote:
> On Jul 31, 2:28�pm, kj <no.em...@please.post> wrote:
> > In <e22013d0-fbad-44e0-919b-ad5bb5f2d...@g19g2000vbi.googlegroups.com> Carl Banks <pavlovevide...@gmail.com> writes:
> >
> > >(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.
>
> 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

r

unread,
Jul 31, 2009, 8:00:28 PM7/31/09
to

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

unread,
Jul 31, 2009, 8:12:43 PM7/31/09
to pytho...@python.org
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

Martin P. Hellwig

unread,
Jul 31, 2009, 8:14:33 PM7/31/09
to
kj wrote:
<cut python has poor documentation explanation>

Well to a level I agree with you.

If you are totally new to programming
_and_
you won't/can't invest in educational material
_and_
have an adversity for looking up resources using a web browser
_and_ don't have the patience for trial and error
*then*
getting proficient with the language is almost impossible.

Sometimes some modules are completely incomprehensible for me and that
is after I have looked at the docstrings, the python doc and examples
found using Google. However usually after combining all three with a
fair bit of experimenting I figure it out, to me that is fun I like that
kind of puzzles but I am aware that this isn't the best possible situation.

Overall I would say a better situation would be if the standard python
documentation would have an *extensive* 'pattern' section for each
module much like, for example, Frederik Lundh did this with his tkinter
documentation. Incorporating these patterns in the standard
documentation would save you some jumping around sites and it is perhaps
more 'trustworthy' coming from the source (pun intended).

I believe that the documentation is all ReST format, so there should be
a way (if there isn't already) to display the extensive documentation
from the interpreter directly for the module you are working with. As
you probably noticed, I actually never bothered to look if this isn't
already the case. Which is a good indication to how much it has actually
bothered me.

Furthermore I like to add to my reply, which is already longer then I
anticipated at first, the thing I don't agree with you is the following
(and comparative in nature): Compared to all other 'popular' languages I
find Python actually very, very good documented and if you can't learn
Python using the available documentation and on-line resources I think
it is unlikely you can learn any other language, whether this is a
programming language or a natural language. Actually, I should have
replaced 'any' with 'anything' followed by a full stop.

--
MPH
http://blog.dcuktec.com
'If consumed, best digested with added seasoning to own preference.'

Mark Lawrence

unread,
Jul 31, 2009, 8:20:32 PM7/31/09
to pytho...@python.org

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

unread,
Jul 31, 2009, 8:39:20 PM7/31/09
to
In article <h4vnm4$jvi$1...@reader1.panix.com>, kj <no.e...@please.post> wrote:
>In <e22013d0-fbad-44e0...@g19g2000vbi.googlegroups.com> Carl Banks <pavlove...@gmail.com> writes:
>>
>>(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.

That's why I use Lynx on a local copy of the Python docs. Next question?
--
Aahz (aa...@pythoncraft.com) <*> 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

unread,
Jul 31, 2009, 9:48:09 PM7/31/09
to
On Fri, 31 Jul 2009 21:28:36 +0000, kj wrote:

> In <e22013d0-fbad-44e0...@g19g2000vbi.googlegroups.com>
> Carl Banks <pavlove...@gmail.com> writes:
>
>>(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.


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.

--
Steven

Tim Chase

unread,
Jul 31, 2009, 10:39:31 PM7/31/09
to Martin P. Hellwig, pytho...@python.org
Martin P. Hellwig wrote:
> kj wrote:
[excerpt of previously snipped content restored]

>> 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.
>
> Well to a level I agree with you.
[snip]

> have an adversity for looking up resources using a web browser

It may not be an adversity for looking things up using a
web-browser, but rather the need to access documentation offline.
Whether on an airplane or simply away from a wifi/landline
connection, there are plenty of times I'm coding offline (another
reason I'm happy to have DVCS tools).

This thread prompted me to go digging a little further, and all
the online docs are available in downloadable format, but you
have to start by going to the base docs and chasing down the
"downloads" rabbit-hole. Perhaps it would be easier if there
were some sort of back-link from individual pages, referencing
the downloadable format package.

Combined with the downloaded HTML version of the docs (there are
PDFs too if you prefer), using a lightweight browser like
lynx/links/dillo, and optionally adding htdig for local
search/indexing, you can access (and search) the full docs offline.

-tkc

Terry Reedy

unread,
Jul 31, 2009, 11:18:35 PM7/31/09
to pytho...@python.org
Tim Chase wrote:

> It may not be an adversity for looking things up using a web-browser,
> but rather the need to access documentation offline. Whether on an
> airplane or simply away from a wifi/landline connection, there are
> plenty of times I'm coding offline (another reason I'm happy to have
> DVCS tools).

This is one area where Windows users seems to have an advantage. The
standard installer includes the doc set as a Windows help file. I often
keep that open in one window while programming in others. I only later
discovered that this was a copy of the online docs ;-), which I only use
to check the in-development version before submitting a doc bug.

Ned Deily

unread,
Aug 1, 2009, 12:55:34 AM8/1/09
to pytho...@python.org
In article <h50c6a$dgf$1...@ger.gmane.org>, Terry Reedy <tjr...@udel.edu>
wrote:

> This is one area where Windows users seems to have an advantage. The
> standard installer includes the doc set as a Windows help file. I often
> keep that open in one window while programming in others. I only later
> discovered that this was a copy of the online docs ;-), which I only use
> to check the in-development version before submitting a doc bug.

The python.org Mac OS X installers include the complete documentation
set for that version in HTML; the IDLE Help menu will open the front
page in a browser (from where you can bookmark it for later use).

--
Ned Deily,
n...@acm.org

Nobody

unread,
Aug 1, 2009, 1:11:18 PM8/1/09
to
On Fri, 31 Jul 2009 20:10:45 +0000, kj wrote:

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

FWIW, I find the module documentation to be mostly adequate.

What's missing is a human-readable language *manual*. The tutorial omits
too much; the language reference may be fine for language lawyering,
but it's not much use otherwise.

jkn

unread,
Aug 1, 2009, 3:01:32 PM8/1/09
to
On Aug 1, 4:18 am, Terry Reedy <tjre...@udel.edu> wrote:

> This is one area where Windows users seems to have an advantage. The
> standard installer includes the doc set as a Windows help file. I often
> keep that open in one window while programming in others. I only later
> discovered that this was a copy of the online docs ;-), which I only use
> to check the in-development version before submitting a doc bug.

The ActiveState distribution also includes the doc set as a CHM file
(the canonical version didn't used to; one reason why I've used
ActiveState in the past).

I run a dual-boot system and have used a CHM (Windows Compiled help
file format) viewer under Linux to read the Windows help file. This
has been pretty handy in the past.

Unfortunately, the combination of the python 2.6 CHM helpfile style,
and the KChmViewer application gives me body text which is almost
unreadable (black text on dark blue background). I'm not sure if this
a bug in KChmViewer but it's pretty annoying. Anyone else see this?

J^n

Tim Golden

unread,
Aug 1, 2009, 3:32:31 PM8/1/09
to pytho...@python.org
jkn wrote:

> The ActiveState distribution also includes the doc set as a CHM file
> (the canonical version didn't used to; one reason why I've used
> ActiveState in the past).

It has done for quite some while now: Python 2.3 was the first
and that was released, what, six years ago. Still, you're right;
it used to use plain HTML.

> Unfortunately, the combination of the python 2.6 CHM helpfile style,
> and the KChmViewer application gives me body text which is almost
> unreadable (black text on dark blue background). I'm not sure if this
> a bug in KChmViewer but it's pretty annoying. Anyone else see this?

This was noised about when the new-style docs were first released.
Somehow (I don't run Linux usually) I had the impression it had
been fixed; presumably not. However, rebuilding the docs is not
at all hard: you just need a Python installation and the
HTMLHelp Workshop. Then you can fiddle about with the CSS to
your heart's content.

TJG

jkn

unread,
Aug 1, 2009, 3:44:14 PM8/1/09
to
Hi Tim

On Aug 1, 8:32 pm, Tim Golden <m...@timgolden.me.uk> wrote:
>
> > Unfortunately, the combination of the python 2.6 CHM helpfile style,
> > and the KChmViewer application gives me body text which is almost
> > unreadable (black text on dark blue background). I'm not sure if this
> > a bug in KChmViewer but it's pretty annoying. Anyone else see this?
>
> This was noised about when the new-style docs were first released.
> Somehow (I don't run Linux usually) I had the impression it had
> been fixed; presumably not. However, rebuilding the docs is not
> at all hard: you just need a Python installation and the
> HTMLHelp Workshop. Then you can fiddle about with the CSS to
> your heart's content.
>

The HTML form of the documents (on python.org) seem fine (dark text on
a light background, with a 'light blue on dark blue' sidebar). I was
guessing that the .CHM was intended to have the same style, and
therefore there was a problem with either my viwer, or with the
conversion. Is this not the case then?

I've just checked using xchm, and this displays OK - but I don't think
it's taking any notice of any styles. FWIW I'm running 4.0-r1; there
is a later release but it's not yet available for my Gentoo
distribution.

Can you point me at any references to this bug in the Python release
world please?

Thanks
J^n


jkn

unread,
Aug 1, 2009, 3:47:50 PM8/1/09
to
update: if I set 'use KHTMLPart-based widget' instead of 'QTextBrowser-
based Widget' to display HTML content in the application settings of
KchmViewer, all is readable. Hurrah!

I wonder if it is picing up some QT stylesheet I have lying around in
an over-clever way...

J^n

Chris Rebert

unread,
Aug 2, 2009, 7:40:20 PM8/2/09
to Mohan Parthasarathy, Python
> On Fri, Jul 31, 2009 at 1:10 PM, kj <no.e...@please.post> wrote:
>> 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.
On Sun, Aug 2, 2009 at 4:22 PM, Mohan Parthasarathy<suru...@gmail.com> wrote:
> I am a newbie and about a month old with Python. There is a wealth of
> material about Python and I am really enjoying learning Python.
>
> One thing that could have helped Python documentation is that instead of the
> very "raw" doc string, it could have used something like PythonDoc (java doc
> style) so that the functions/classes are documented better. At least I am
> planning to use PythonDoc for the code that I am going to write. Let me know
> if there is a better one..

If you use reStructuredText (http://docutils.sf.net/rst.html), you can
leverage Sphinx (http://sphinx.pocoo.org/), which generates the
superb-looking official Python docs.

Cheers,
Chris

P.S. Please don't top-post (http://en.wikipedia.org/wiki/Top-post) in
the future.
--
http://blog.rebertia.com

Christian Heimes

unread,
Aug 2, 2009, 8:39:34 PM8/2/09
to pytho...@python.org
Mohan Parthasarathy schrieb:

> I am a newbie and about a month old with Python. There is a wealth of
> material about Python and I am really enjoying learning Python.
>
> One thing that could have helped Python documentation is that instead of the
> very "raw" doc string, it could have used something like PythonDoc (java doc
> style) so that the functions/classes are documented better. At least I am
> planning to use PythonDoc for the code that I am going to write. Let me know
> if there is a better one..

Several projects are trying to improve the doc strings with an extended
syntax. Personally I prefer the epytext syntax from epydoc [1]. It's a
JavaDoc like markup language that extends the raw doc strings with
useful information.

Christian

[1] http://epydoc.sourceforge.net/manual-epytext.html

Ethan Furman

unread,
Aug 3, 2009, 12:00:43 PM8/3/09
to pytho...@python.org

And if you do smile at them, don't show your teeth!

~Ethan~

David Lyon

unread,
Aug 4, 2009, 1:55:20 AM8/4/09
to Kee Nethery, pytho...@python.org

It isn't totally about the writers...

Peoples egos are also at stake - it seems.

If "Fred X wrote Doc Y".. they don't want their name taken off.. So
they generally speaking don't want the docs changed.

If you talk too much about docs.. you can be told you're OT..

even in a thread about docs...

alex23

unread,
Aug 4, 2009, 2:21:20 AM8/4/09
to
On Aug 4, 3:55 pm, David Lyon <david.l...@preisshare.net> wrote:
> It isn't totally about the writers...
> Peoples egos are also at stake - it seems.

Citation please.

> If "Fred X wrote Doc Y".. they don't want their name taken off.. So
> they generally speaking don't want the docs changed.

Ditto.

> If you talk too much about docs.. you can be told you're OT..
> even in a thread about docs...

And again.

All I've _ever_ seen (on this group at least) is the much repeated
phrase "All patches to the docs are welcomed". If you'd like to cast
aspersions on the characters of those doing the work over actually
contributing yourself, you're certainly free to do so, just don't
expect your claims to be taken seriously.

Other people's refusal to do the work that _you_ consider to be
necessary isn't "ego".

r

unread,
Aug 5, 2009, 11:35:43 PM8/5/09
to
On Aug 4, 12:55 am, David Lyon <david.l...@preisshare.net> wrote:
> It isn't totally about the writers...
> Peoples egos are also at stake - it seems.
> If "Fred X wrote Doc Y".. they don't want their name taken off.. So
> they generally speaking don't want the docs changed.
> If you talk too much about docs.. you can be told you're OT..
> even in a thread about docs...

This is the most honest post within this thread. Yes i believe --
although it does not make me happy-- that many within this community
are hostile, vulgar, and viscous towards any notion of change if it
comes from outside the "insiders" group (and even sometimes from the
inside). Which is very sad.

Yes sometimes people are just trolling, but this tread has nothing to
do with trolling. kj has a legitimate complaint. Do i believe the docs
are a complete waste of bytes, No! Many people have invested tons of
hard work into them (and i thank them for their hard work). But i do
believe --like all things in this word-- perfection is always just out
of hands reach, we must constantly seek perfection because we can
never attain it. Like any group effort, eventually it will adopt the
idioms of self indulgence. Python dev needs the input of those who are
not experts in the language --especially in the realm of docs.

It is so easy to forget the struggles we face when learning something
new. The accessibility and appeal of Python to new users is in the
best interest of this community. If you don't believe that, you are
pissing on all the years of hard work that has been put in here. You
might as well just tell Guido to "close up shop"

I have posted this once before but i will post it again. Please read
Christopher's words carefully because they apply to this community in
a big way...Don't fall into the trap of narcissism.

Christopher Lasch referring to the pitfalls of Narcissistic societies:

"""In such a society of constant competition, there can be no allies,
and little transparency. The threats to
acquisitions of social symbols are so numerous, varied and frequently
incomprehensible, that defensiveness, as well as competitiveness,
becomes a way of life. Any real sense of community is undermined -- or
even destroyed -- to be replaced by virtual equivalents that strive,
unsuccessfully, to synthesize a sense of community."""

While I agree that some narcissism is vital to an individuals ego in
competitive atmospheres, I do not believe the Python community
warrants this need.

Terry Reedy

unread,
Aug 6, 2009, 9:55:04 AM8/6/09
to pytho...@python.org
RayS wrote:
> At 08:35 PM 8/5/2009 -0700, r wrote:
>> """... Any real sense of community is undermined -- or

>> even destroyed -- to be replaced by virtual equivalents that strive,
>> unsuccessfully, to synthesize a sense of community."""
>
> I've brought up the idea of the quasi-community doc that PHP uses to
> good effect.

And what have you done about setting up such a project?

> http://www.php.net/manual/en/language.types.array.php is a prime example
> where 2/3 of the "doc" is user-contributed comments and code.

I consider consider this to an unreadable mishmash. If you and others
want something like that, do it. And quite bitching about the work of
those of us who have done something compact and readable. We are all
volunteers here.

tjr

Kee Nethery

unread,
Aug 6, 2009, 10:39:10 AM8/6/09
to pytho...@python.org

As I struggle through trying to figure out how to make python do
simple stuff for me, I frequently generate samples. If some volunteer
here would point me towards the documentation that would tell me how I
can alter the existing Python docs to include sample code, I'd be more
than happy to do so.

I would like to "do it". Please point me to the docs that tell me how
to "do it" so that we people with newbie questions and a need for
examples can get out of your way and "do it" ourselves.

Thanks,
Kee Nethery

alex23

unread,
Aug 6, 2009, 11:52:51 AM8/6/09
to
Kee Nethery wrote:
> As I struggle through trying to figure out how to make python do  
> simple stuff for me, I frequently generate samples. If some volunteer  
> here would point me towards the documentation that would tell me how I  
> can alter the existing Python docs to include sample code, I'd be more  
> than happy to do so.

No offence, but the last thing the official documentation needs is
example code written by people learning how to code. Suggest changes,
request clarifications, submit samples for review, sure, but direct
modification by users? I've seen the PHP docs; thanks but no thanks.

> I would like to "do it". Please point me to the docs that tell me how  
> to "do it" so that we people with newbie questions and a need for  
> examples can get out of your way and "do it" ourselves.

You start by reading this: http://docs.python.org/documenting/index.html
And this: http://www.python.org/dev/contributing/
And this: http://wiki.python.org/moin/WikiGuidelines

The first link, which directly answers your question, is clearly
listed on the doc contents page as "Documenting Python". I'm uncertain
how the docs could be made any _more_ helpful if people aren't
prepared to put effort into reading them. We're a long way away from
direct upload to the brain, unfortunately.

If you're learning the language, you should also consider using more
appropriate resources:
http://mail.python.org/mailman/listinfo/tutor
http://www.doughellmann.com/PyMOTW/
http://diveintopython.org/

The documentation cannot be all things to all people, and it most
certainly can't be a guide to general programming, which is what often
seems to be the issue with novice users. Python's a great language to
learn how to program in, sure, but I would hate to see that become the
focus of the docs.

Sion Arrowsmith

unread,
Aug 6, 2009, 12:11:24 PM8/6/09
to
Terry Reedy <tjr...@udel.edu> wrote:>> [ ... ]

>I consider consider this to an unreadable mishmash.
[compared to]
> something compact and readable.

Are you talking about the language or the documentation? 9-)

(Actually, that might be a serious point: does the approach to
documentation reflect language design?)

--
\S

under construction

Paul Rubin

unread,
Aug 6, 2009, 12:20:33 PM8/6/09
to
alex23 <wuw...@gmail.com> writes:
> No offence, but the last thing the official documentation needs is
> example code written by people learning how to code. Suggest changes,
> request clarifications, submit samples for review, sure, but direct
> modification by users? I've seen the PHP docs; thanks but no thanks.

The PHP docs as I remember are sort of regular (non-publically
editable) doc pages, each of which has a public discussion thread
where people can post questions and answers about the topic of that
doc page. I thought it worked really well. The main thing is that
the good stuff from the comment section gets folded into the actual
doc now and then.

There is something similar with the PostgreSQL docs. There is also
Real World Haskell (http://book.realworld.haskell.org) which has a lot
of interspersed user comments. It would be cool if Python's doc site
did something like it too.

r

unread,
Aug 6, 2009, 2:33:06 PM8/6/09
to
On Aug 6, 11:20 am, Paul Rubin <http://phr...@NOSPAM.invalid> wrote:
...(snip)

> There is something similar with the PostgreSQL docs.  There is also
> Real World Haskell (http://book.realworld.haskell.org) which has a lot
> of interspersed user comments.  It would be cool if Python's doc site
> did something like it too.

hear! hear!

Wesley Chun

unread,
Aug 6, 2009, 3:14:21 PM8/6/09
to
On Jul 31, 1:10 pm, kj <no.em...@please.post> wrote:
> 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:


kj,

welcome to Python! i'm sorry that you find the documentation lacking.
the one thing about the docs is that they're just pointers to get you
started and aren't very comprehensive. there are plenty of good online
tutorials out there as well as books. in fact, one of my main
motivations for writing "Core Python Programming" was because when i
learned Python 13 years ago, the online docs were enough to get me
started but did not have enough info to help me become an intermediate
Python programmer. there were only *2*(!) Python books out there, and
they were special-topic oriented, not ones to learn the language from.
it took almost a year and a half to write, but from what i hear from
readers and what has been said in reviews, it's pretty comprehensive,
and is a good book to learn Python from. i only wish that *i* had it
when i was learning!

Most "Python experts" do not have the entire language memorized, so
everyone has to look at the docs from time-to-time, not just
beginners. i'll either hit up http://docs.python.org/library/MODULE.html
or flip open my Nutshell or PER references, and finally, i'll google
if i have to (rare). the Python docs are the language manuals and not
necessarily full reference texts, so you have to just take them for
what they are.

hope this helps!
-- wesley
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
"Core Python Programming", Prentice Hall, (c)2007,2001
"Python Fundamentals", Prentice Hall, (c)2009
http://corepython.com

wesley.j.chun :: wescpy-at-gmail.com
python training and technical consulting
cyberweb.consulting : silicon valley, ca
http://cyberwebconsulting.com

alex23

unread,
Aug 7, 2009, 1:41:17 AM8/7/09
to
Paul Rubin <http://phr...@NOSPAM.invalid> wrote:
> The PHP docs as I remember are sort of regular (non-publically
> editable) doc pages, each of which has a public discussion thread
> where people can post questions and answers about the topic of that
> doc page.  I thought it worked really well.  The main thing is that
> the good stuff from the comment section gets folded into the actual
> doc now and then.

I'd still like to see this kept out of the official docs as much as
possible, mostly for reasons of brevity & clarity. I think the
official docs should be considered definitive and not require a
hermeneutic evaluation against user comments to ensure they're still
correct...

How about a secondary site that embeds the docs and provides
commenting functionality around it? That's certainly a finitely scoped
project that those with issues about the docs could establish and
contribute to, with the possibility of it gaining official support
later once it gains traction.

Jean-Michel Pichavant

unread,
Aug 7, 2009, 4:55:51 AM8/7/09
to alex23, pytho...@python.org
Very good Idea. I'd like to get a commented/user improved python
documentation site with examples and I also love the current python
documentation.

JM

r

unread,
Aug 7, 2009, 5:22:50 AM8/7/09
to
On Aug 7, 12:41 am, alex23 <wuwe...@gmail.com> wrote:
...(snip)

> How about a secondary site that embeds the docs and provides
> commenting functionality around it? That's certainly a finitely scoped
> project that those with issues about the docs could establish and
> contribute to, with the possibility of it gaining official support
> later once it gains traction.

This is by far the most helpful and honest post i have ever seen by
our friend alex23. I have a new found respect for you sir, thanks

-R

Paul Rubin

unread,
Aug 7, 2009, 6:43:48 AM8/7/09
to
alex23 <wuw...@gmail.com> writes:
> I'd still like to see this kept out of the official docs as much as
> possible, mostly for reasons of brevity & clarity. I think the
> official docs should be considered definitive and not require a
> hermeneutic evaluation against user comments to ensure they're still
> correct...

Such evaluation would only do them good. The official docs are full
of errors and omissions, which is why we have this thread going on
here in the newsgroup.

Dave Angel

unread,
Aug 7, 2009, 8:15:11 AM8/7/09
to alex23, pytho...@python.org
I share your concern about unmonitored comments. However, it seems a
useful possibility would be for the "official" pages to each have
specially-marked links that possibly lead to such user comments.
Clearly they'd have to marked carefully, so that naive users don't
confuse the two. But otherwise, it feels like a good idea.

In my case, I usually access the docs via the Windows help file. So
it'd be quite easy for me to recognize that once I've gotten to a
browser page, I'm not in Kansas any more. But that could be also
accomplished by having a very different stylesheet for the user comments
page.

DaveA

alex23

unread,
Aug 7, 2009, 10:05:20 AM8/7/09
to
Paul Rubin <http://phr...@NOSPAM.invalid> wrote:
> Such evaluation would only do them good.  The official docs are full
> of errors and omissions, which is why we have this thread going on
> here in the newsgroup.

And there is a process for reporting and correcting such errors and
omissions, which is what I pointed out in my post.

Kee Nethery

unread,
Aug 7, 2009, 12:03:37 PM8/7/09
to pytho...@python.org
During all this conversation there was a ticket posted in the bug
tracking system with the suggestion of each section in the official
docs linking to a fixed wiki page that can contain user contributions.

The ticket has been closed because this addition to the official docs
is already in the works.

So ... to everyone who thinks there needs to be a place for user
comments to augment the official docs, it's supposed to happen. Same
with corrections to the docs, there is supposed to be a place per
section where people can post corrections to the docs.

I'm looking forward to the acceleration of improvements to the
official docs based upon easy to provide user feedback. Glad to see
that the bug tracking system is going to not be the primary means for
documentation changes.

Kee

r

unread,
Aug 7, 2009, 1:43:05 PM8/7/09
to
On Aug 7, 11:03 am, Kee Nethery <k...@kagi.com> wrote:
...(snip)

> I'm looking forward to the acceleration of improvements to the  
> official docs based upon easy to provide user feedback. Glad to see  
> that the bug tracking system is going to not be the primary means for  
> documentation changes.

+1

alex23

unread,
Aug 7, 2009, 1:48:22 PM8/7/09
to
Kee Nethery <k...@kagi.com> wrote:
> I'm looking forward to the acceleration of improvements to the  
> official docs based upon easy to provide user feedback. Glad to see  
> that the bug tracking system is going to not be the primary means for  
> documentation changes.

I'm not sure what you see as being fundamentally different between
open access to a bug tracker & open access to a wiki, other than it
being a lot more difficult to have threaded discussion on a wiki.

Why exactly is posting an open comment on a bug tracker somehow
inferior to posting an open comment on a wiki?

David Robinow

unread,
Aug 7, 2009, 2:05:35 PM8/7/09
to alex23, pytho...@python.org
On Fri, Aug 7, 2009 at 1:48 PM, alex23<wuw...@gmail.com> wrote:
> Why exactly is posting an open comment on a bug tracker somehow
> inferior to posting an open comment on a wiki?
When one believes that development is controlled by a cabal which is
jealous of outsiders and actively prevents improvements to the docs,
any change, even if only in perception, helps to weaken the hold of
the evil forces holding back the success of Python.

alex23

unread,
Aug 7, 2009, 2:30:41 PM8/7/09
to
David Robinow <drobi...@gmail.com> wrote:
>  When one believes that development is controlled by a cabal which is
> jealous of outsiders and actively prevents improvements to the docs,
> any change, even if only in perception, helps to weaken the hold of
> the evil forces holding back the success of Python.

Yeah, it's clearly all ego and assholes that's preventing Python from
being the enochian equivalent of programming languages :)

Kee Nethery

unread,
Aug 7, 2009, 4:35:26 PM8/7/09
to pytho...@python.org

It's a good question and deserves a good answer.

* Fewer Steps
* Immediate
* Does not need to be formally reviewed
* Easier to search

For all these comments, assume the starting point is the section in a
web page that documents a specific python function. Assume the user is
using the documentation for the first time in attempt to convert to
Python. Thus, this is the only official Python page they have ever
seen, they found it via Google and went directly to it. For example
purposes, I'll use the following page:
http://docs.python.org/reference/lexical_analysis.html
Lets say the user is in section 2.1.3 Comments

Here's the scenario: The user wanted to include "#" in one of their
strings and the IDE kept interpreting it as a comment. But they really
need to use that character in the string. Eventually they find out
that they can escape the character in their string so that Python
stops thinking it is the beginning of a comment. They want other users
to not suffer through the same thing, and they want to contribute to
the betterment of Python, so they want this information saved so that
others can avoid the mistake they were making.

* Fewer Steps:

With the bug tracking system, their only option is to lobby to get the
documentation changed. Lets assume that Python experts all agree that
the docs should get updated with this gotcha (which as a newbie, they
are not sure that is a valid assumption and would probably just halt
in their quest to get the docs updated). But assuming everyone agrees
this is a valuable addition to the docs so that others can avoid the
same error, where on this page dues the user submit this bug? There is
no link on this page to the bug tracking system.

Lets assume they find the bug tracking system through determined
efforts because they believe there has to be such a thing and they are
absolutely sure the powers that be want their input. When they find
the bug tracking system ... they have to create a user account. Then
they have to wait for the confirming email. Finally they get access to
the bug tracking system and being a good citizen, they want to make
sure that they are not duplicating a previously entered bug. What do
they search on? Do they search for 2.1.3? Do they search for "#"?
Chances are, even if they do a whole set of searches, and if there
really is already another bug entered for the exact same issue, they
are unlikely to find it.

So they create a bug and now they need to go back and reference the
link (find the page from their browser history) and type up why they
think their modification to the documentation is worthy. Then once the
bug is submitted ... you get the picture, there are a gazillion steps
just to submit a bug. Most people do not bother to submit little
helpful hints to the docs because it is too much of a pain to do so
and there is zero confidence that as a newbie, anyone cares about what
they found confusing, after all, they are just a newbie and not worthy
of altering the documentation. (Certainly that opinion has been
expressed several times on this mailing list).

With a wiki article tied to each section in the docs, they click on
the link and are taken directly to the wiki page of user contributions
for this specific 2.1.3 section of the docs. They scan the user
comments and see that no one else entered a note about this gotcha.
They click on the edit button, enter their gotcha, save, and they are
done.

* Immediate:

With the bug tracking system, they struggle to find a place to
contribute and then once they make their contribution, they have no
idea whether anyone will ever see it and whether they have just wasted
a bunch of time.

With the wiki link for that section, in less than a minute, they can
see the comments they have left attached to that specific section so
that others can see them too and perhaps avoid the same mistake they
made. A wiki link encourages new users to be contributors. New users
are the absolute best source of what is confusing to a new user.

* Does not need to be formally reviewed:

With the bug tracking system, each bug has to be reviewed by a
volunteer, analyzed, commented on, dealt with.

With a wiki, no one has to look at user comments. They can just leave
them there and ignore them. Other users can police the content and add
additional comments or examples. All the while none of the official
volunteers have to get in the loop. If some official volunteer wants
to improve the docs, they can scan the wiki contributions and use that
as the source for official changes to the docs.

* Easier to search:

Very few people would think to search the bug tracking system for help
with some specific function. If someone is having trouble with the #
sign in their strings, the bug tracking system is not going to be at
the top of their list for search locations, especially when the bug
tracking system is not mentioned and when found requires a confirmed
login.

With a wiki link, the first thing someone will do is click on that to
see if anyone else left notes about the specific problem. If there was
no answer there, they'd search Google and try bunches of different
wordings looking for some clue as to what is happening. I doubt most
users (except for expert users) would ever search the bug tracking
system for hints on why their code is not doing what they expect.

My 2 cents,
Kee

r

unread,
Aug 7, 2009, 8:33:09 PM8/7/09
to
On Aug 7, 3:35 pm, Kee Nethery <k...@kagi.com> wrote:
(snip)

Kee,
that was an eloquent and enlighting post and i think it speaks volumes
to the lack of inclusion of all Pythoneers in this community. Not to
mention the viscous attitudes and self indulgence we have around here.

For those of you with ADD, Kee was speaking to the hurdles one must
overcome to change even the most minor things within this community.
Change around here almost parallels an act-of-congress with it's de-
motivating burdens that beset a new python user who may wish to add
his or her 2 pennies to the Python wishing well. And i believe like
Kee, most of them just give up and say
"""Oh Well, F### it!"""

Not to mention the never ending droves of naysayers, bullies, smart-
arses, and egomaniacs with their minions and sock-puppets ready at
moments notice to pounce on (and utterly destroy) any feeble noob who
dares to try and enhance the user experience in Python for all of us.

Steven D'Aprano

unread,
Aug 8, 2009, 12:25:31 AM8/8/09
to
On Fri, 07 Aug 2009 13:35:26 -0700, Kee Nethery wrote:


> > Why exactly is posting an open comment on a bug tracker somehow
> > inferior to posting an open comment on a wiki?
>
> It's a good question and deserves a good answer.
>
> * Fewer Steps
> * Immediate
> * Does not need to be formally reviewed
> * Easier to search

The last one is actually wrong, because the Python bug tracker is indexed
by Google.

As for the rest, you're right that the current bug-tracker puts up
barriers to people submitting comments and bugs. That's actually a good
thing. The only thing worse than not enough information is too much
information, and the current situation does a good job of discouraging
the sorts of people who submit bad bug reports (e.g. duplicates of bug
reports, bug reports for things fixed years ago, bug reports that are due
to mistakes in their code, etc.).


> For example
> purposes, I'll use the following page:
> http://docs.python.org/reference/lexical_analysis.html
> Lets say the user is in section 2.1.3 Comments

Disclaimer: python.org is down at the moment, so I can't check that page
to see precisely what you're talking about.


> Here's the scenario: The user wanted to include "#" in one of their
> strings and the IDE kept interpreting it as a comment. But they really
> need to use that character in the string. Eventually they find out that
> they can escape the character in their string so that Python stops
> thinking it is the beginning of a comment.

Er, that would be a bug in the IDE, surely? Inside strings, # is an
ordinary character with no special meaning.


>>> s = "this is a string with an unescaped # in it"
>>> s
'this is a string with an unescaped # in it'


The Python docs are supposed to be about Python the language, not work-
arounds for IDE bugs.


[...]


> Lets assume that Python experts all agree that
> the docs should get updated with this gotcha (which as a newbie, they
> are not sure that is a valid assumption and would probably just halt
> in their quest to get the docs updated).

Good.

As a newbie, you SHOULD assume that anything you think is a bug is
probably a bug in YOUR code, not Python, and the same goes for
documentation bugs. If you don't understand something in the docs,
chances are that it's a problem with you, not the docs. Your first port
of call should be the tutor list, or here, and not to "fix" the docs by
putting in noise that just gets in the way of the intended audience,
namely experienced developers.


> and there is zero confidence that as a newbie, anyone cares about what
> they found confusing, after all, they are just a newbie and not worthy
> of altering the documentation. (Certainly that opinion has been
> expressed several times on this mailing list).

No, we care. We just don't want to have the docs filled with all the hand-
holding and introductory stuff which the newbie needs. As a developer,
you will outgrow the need for training wheels. Why force training wheels
on the docs that you will be referring to for your entire career as a
programmer, when you only need them for the first few months? There are
plenty of docs aimed at newbies, and mailing lists where you can ask
questions.

Putting user-comments on a separate page separates the noisy, low-value
comments from the good stuff, but it increases the efforts needed by the
webpage admin (who is going to deal with the comment spam? who is going
to go through the user-comments stripping out the total nonsense put in
by helpful ignoramuses?). It works for Wikipedia, because there are tens
of thousands of users contributing small amounts of effort, and hundreds
putting in a lot of effort, but even there there is a major problem with
vandalism. We don't have those resources.

By the way, if a person wants to contribute, and can demonstrate
competence, reliability, good-sense and trustworthiness, there's no
reason why he or she couldn't get a check-in account for the Python docs.
(All the Python docs are written by volunteers.) A good way to
demonstrate these things is by submitting good-quality doc improvements
to the bug-tracker. If a person can't be bothered to do so, because it
requires effort to get an account, that goes a long way to demonstrating
the *lack* of reliability which will disqualify them from the job.


> Very few people would think to search the bug tracking system for help
> with some specific function. If someone is having trouble with the #
> sign in their strings, the bug tracking system is not going to be at
> the top of their list for search locations, especially when the bug
> tracking system is not mentioned and when found requires a confirmed
> login.

You don't need a login to view bug reports, only to modify them.

If you want an open-access documentation system go right ahead and build
one. There are plenty of wikis available to use, and the Python docs are
freely available as your starting point. I might even contribute myself.
I just don't want it mixed in with the official docs: I want a clear
separation between what's officially sanctioned and what's not.


--
Steven

Carl Banks

unread,
Aug 8, 2009, 12:46:51 AM8/8/09
to
On Aug 7, 9:25 pm, Steven D'Aprano <st...@REMOVE-THIS-

cybersource.com.au> wrote:
> If you want an open-access documentation system go right ahead and build
> one. There are plenty of wikis available to use, and the Python docs are
> freely available as your starting point. I might even contribute myself.
> I just don't want it mixed in with the official docs: I want a clear
> separation between what's officially sanctioned and what's not.

The PyGame documentation has a "Click to view comments" box. That
would be A. low profile, and B. distinct from official documentation
enough for me.

It'd probably be useful, but might also attract spam and lots of
useless fluff, because it's likely to be much higher volume than
documentation on other projects.


Carl Banks

Paul Rubin

unread,
Aug 8, 2009, 1:06:23 AM8/8/09
to
Steven D'Aprano <st...@REMOVE-THIS-cybersource.com.au> writes:
> As for the rest, you're right that the current bug-tracker puts up
> barriers to people submitting comments and bugs. That's actually a good
> thing. The only thing worse than not enough information is too much
> information, and the current situation does a good job of discouraging
> the sorts of people who submit bad bug reports (e.g. duplicates of bug
> reports, bug reports for things fixed years ago, bug reports that are due
> to mistakes in their code, etc.).

Stephen, Alex, etc.: have you actually used the php.net doc system?
Don't knock it til you've tried it. IMO it is superior to Python's
system. I don't use PHP much these days.

Roel Schroeven

unread,
Aug 8, 2009, 2:39:49 AM8/8/09
to
Paul Rubin schreef:

I have to use PHP from time to time, in which cases I often have to use
the manual on php.net. I don't like it at all.

The official documentation is often incomplete, leaving out the details
I need and forcing me to read the comments.

Which I don't want to do, since many comments show a lack of
understanding of the subject matter. I have to read all of them, trying
to find out which ones are correct and which ones are wrong (or
misleading) to get the complete picture.


I like Python's documentation, where I can be confident that the
documentation is correct (except in the case of the very exceptional
bug) and mostly clear, much better.

--
The saddest aspect of life right now is that science gathers knowledge
faster than society gathers wisdom.
-- Isaac Asimov

Roel Schroeven

koranthala

unread,
Aug 8, 2009, 3:26:50 AM8/8/09
to