Python docs disappointing

[Wesley Chun]

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]

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]

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.

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]

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]

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]

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.

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]

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]

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]

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]

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]

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]

 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]

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?

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]

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

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.

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

 

[Carl Banks]

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]

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]

Paul Rubin schreef:

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.

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]

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

The best example that I have seen is djangobook.
The comment system in it is quite exquisite.
It would be good for the Python docs to have such a mechanism.

 

[Mark Lawrence]

As someone trying to learn the language I want to say that the tone on
this list towards people who are trying to learn Python feels like it
has become anti-newbies.
[snip]

Kee Nethery

My gut feeling (which could of course be wrong) is that many hard core
Pythonistas are cheesed off with newbies who refuse to help themselves.
No evidence that that they've tried any Python tutorial. No evidence
that that they've searched anywhere in an attempt to resolve the problem
before posting. "This code doesn't work, please fix it". Response
often "Please post your actual code, or a snippet that gives the same
exception, and give the complete exception details".

Show that you have made an attempt to help yourself, and the response
here is almost certainly 100% helpful.

Further, I have seen many requests here which are nothing really to do
with Python, say a query about which algorithm to use. Response "Not
really a Python question, but try ...". Put the same question on (say)
the C ng and you'd be told in no uncertain terms to Foxtrot Oscar.