Python docs disappointing

[Paul Rubin]

- if people are keen on a Python wiki, then by all means publish one,
just don't expect the Python dev team to build and manage it for you;

There are already some nice ones at:

http://en.wikibooks.org/wiki/Python

 

[Raymond Hettinger]

[Paul Rubin]

I think the Python tutorial is aimed at users who are newbies to
Python but not newbies to programming.  Writing a tutorial for total
newbies is a completely different problem, that would result in a much
different document that's less useful to the existing tutorial's
intended audience.

There is more than one right answer to "what is the best tutorial
for different people". The www.python.org website lists a number
of tutorials. Here is the page specifically marked for those
who are new to programming:

http://wiki.python.org/moin/BeginnersGuide


Raymond

 

[Paul Rubin]

Some say the tutorial is not meant for non-programmers, but for
programmers with no Python experience. So! How does that justify
obstruction of the tut? Why not present the same information in a way
both can easily understand?

I agree that a tutorial for non-programmers would be useful, but it's
better to have it as a separate document. The existing tutorial helps
experienced programmers get started with Python very quickly, by
checking off familiar features from other languages and saying how
Python implements them. Someone familiar with (say) Java or C++ can
read it in a few minutes and start contributing to a Python project.
Pitching it to complete beginners would require covering a lot of
ground that is already well known to someone who programs in other
languages, and would slow it down too much.

 

[Paul Rubin]

Here is the page specifically marked for those who are new to programming:
http://wiki.python.org/moin/BeginnersGuide

Oh cool, I didn't know about that one.

 

[max bianco]

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.

I assume I am misunderstanding you here and you meant something else?
Python is paraded as a good language for beginners. Is this a false
statement or a secondary objective? Or are the docs only meant for
experienced developers? That just doesn't sound right.

 

[max bianco]

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.

Learning a new language is difficult enough without seeing other newbies
getting shamed for not knowing everything there is to know about Python
before asking their questions.

Well I have to say your right about the tone but using google before
you ask is not an unreasonable expectation. I have of course broken
this golden rule myself on mailing lists myself , however a response
like use google is totally acceptable to me.

 

[r]

Ok people follow me here. Open your winders help file and click the
"Tutorial" link. What is this FLUFF doing here!?!?! Where is the damn
index? Where is the damn tutorial? I want to learn Python not read the
HISTORY OF THE WORLD.

Upon clicking the "Tutorial" link pre 2.6, a nice menu was placed
before your eyes, WHERE IS IT!?!??? Good thing i know the language or
i would have given up already!!!!

 

[r]

Ah Ha! the docs are broken and i was right all along! Are the good
folks at Python dev rolling a new installer as we speak, or we must
wait for new version?

 

[Mark Lawrence]

Ah Ha! the docs are broken and i was right all along! Are the good
folks at Python dev rolling a new installer as we speak, or we must
wait for new version?

As I pointed out a few minutes ago thicko, the new version has been
available for months.

 

[Carl Banks]

As I pointed out a few minutes ago thicko, the new version has been
available for months.

Hello,

I'm mailing you to kindly request, again, that you please stop
validating "r"'s disruptiveness by responding to him on
comp.lang.python. Thank you.

Carl Banks

 

[rurpy]

Discussion here is spitting into the wind. The noise-to-signal ratio is
high enough that the people who can fix an issue aren't likely to see it
here. Unless somebody raises a report in the bug tracker, it will go
nowhere, fast.

The point isn't always to gain a core developer's attention --
sometimes it is to figure out a good approach before proposing
something concrete.

The same happens for issues on the dev list: I can't count how many times
people there have said "put it in the bug tracker, or it will be
forgotten".

On the contrary, there are many issues raised there that are
discussed there or result in the response, "take it to python-
ideas". Not every issue to so well-baked that it is ready for
a tracker issue with patch. There are some things that need
discussion before investing a lot of effort in them.

The same way you would submit a tracker issue for anything.

"Documentation bug: Data types are misplaced in the library manual
instead of the language manual.

Suggested alternative: move page docs.python.org/xyz.html to abc.html"

But that's the problem. Such a reorg is not a simple matter
of moving a file from here to there. It will require a lot
moving about of sections and a lot of word-smithing to glue
them back together again in a coherent way.

A tracker issue, even one that was fairly specific about
how things should be reorganized but which did not provide
all the needed changes (a large patch) would almost certainly
be ignored or rejected. But providing a large patch raises
two questions. How likely is it to be be accepted?
(Something anyone would want to know before investing the time.)
And how to actually do the work needed to generate it (it could
be a very large amount of work for an individual and I don't
think it can be broken down into small independent issues.)
How is one to test the waters as to acceptability, or solicit
help, if one simply submits a tracker issue?

There's a difference between insufficiently good writing and poor
writing: think of grading the docs, where 100 is "perfect in every way"
and -100 is "perfectly awful in every possible way". (It's not a linear
scale.) A score of 0 is "mediocre, just barely acceptable". Poor writing
has a negative score. In my opinion, Python's docs are perhaps a 40 or
50, significantly better than most technical docs I've seen.

There is no objective way of rating docs. My evaluation results
in part from the fact that I was able to learn Perl using only
the man pages. I seriously attempted the same with the supposedly
easier-to-learn Python but was not able to and had to resort to
other web resources and buying Beazly's book.

Before you reply that tutorials are for learning, not reference
manuals, I will disagree. A well written reference manual will
provide all the information needed to understand a language (albeit
arranged differently than the linear form of a tutorial), and I
have learned several languages in addition to Perl from their
reference materials. Which is why I attribute my failure to do
so with Python to be the docs' fault.

[...]

I can rewrite some section so it sounds good to me, but likely it will
be just as bad (perhaps in different ways) that what is there.

Bug reports are valuable even if you don't have the skills to provide a
patch. Bug reports with patches are even more valuable, but that doesn't
mean that the failure to provide a patch *necessarily* dooms your report
to oblivion.

The post that started this thread proposed something like paying
professional writers to improve the docs. This may or may not be a
practical suggestion. But the immediate response it engendered was an
auto-immune-like group response: the docs are great already, don't
complain, fix them yourself, yada, yada; the same response that any
criticism of free software produces.

I haven't seen any such knee-jerk responses. What I've seen is a set of
sensible, *practical* advice:

- complaining on its own, especially here, is pointless;

I don't think that is true. (Or rather, the extent that it is true
is determined by the attitudes here.)

- Python is a community effort, if you see something that needs fixing,
do something about it;

Pointing out something that needs fixing *is* doing something
about it. Maybe not as much as you'd like but from each according
to his ability...

- many of us DON'T want arbitrary people "correcting" the official docs
without oversight, and believe that would be a disaster (arbitrary people
aren't give check-in privileges to add code to Python's standard library,
nor should they be given check-in privileges to add docs);

Agreed. I hope that was clear from my earlier post.

- if people are keen on a Python wiki, then by all means publish one,
just don't expect the Python dev team to build and manage it for you;

As luminous a Pythoneer as Fredrik Lundh set up a documentation
wiki to collect user contributions but it has faded away. If
he couldn't pull it off then I'd say most other attempts without
the backing of python.org are almost certainly doomed to failure.
However, were the Python docs site to provide a wiki, along
with a mechanism to migrate suggestions developed on the wiki
into the docs, it might well be a viable (and easier because of
the wysiwyg effect) way of improving the docs. As other have
pointed out, Postgresql, PHP, and Haskell have done so.
Now maybe there are good reasons not to do that. But your hand-
waving is not one of them.

- bug reports and patches to the docs are ALWAYS welcome, even if they
are rejected;

Of course. The cost for briefly looking at a report before
rejecting it is very low. However the cost for producing it
can be much higher. I'm not saying that that is what happens,
just that your statement considers only the pov of the issue
handlers, not the submitters.

- if you don't have the skills to fix a bug (including doc bugs), an
alternative is to pay somebody else to do so instead.

That there are alternatives was not my point. My point was
that there are perhaps *other* alternatives too, but anyone
who tries to explore them here usually gets buried under a
mass of negativity.

It's really too bad the the python community can't seriously discuss
ways to improves the docs. There are other possibilities for instance
the Fedora Docs project (can't say I'm impressed by what they've
produced but that doesn't mean their model is useless). There is a need
for an approval process managed by someone who actually understands what
good technical writing is. And perhaps editors who can polish or work
with programmers who provide the raw technical description of some
module.

Yes, you're correct.

[sarcasm] Now that we've agreed on what needs to be done, the problem is
solved!!! [end sarcasm]

Anyone who's ever been to AA knows that the first step to
solving a problem is to acknowledge the problem exists.
As long as every "the docs sux" complaint is met here with
the standard responses that I've mentioned, rather than, "yes,
they do have some problems, what do you think we should do
about them?", the docs will continue to sux. But as I said
maybe that's just the way it is.

You want community input into the docs, but you're not willing to give
that input except to bitch and moan and sook that the tracker is no good.

I have not done any "bitching and moaning". I tried to
explain a group reaction that affects python negatively
(IMO) by rejecting any consideration of ways of improving
the docs other than submitting tracker issues.
That you pejoratively label it "bitching and moaning"
I count as evidence supporting my view.

Even if the PSF had a full-time team of professional documentation
writers and editors, guess what, you would STILL need to submit issues to
the bug tracker, because otherwise THEY WON'T BE TRACKED.

Maybe, maybe not. Depends on what development process the
(hypothetical) doc team chooses to use is.

Ultimately it boils down to two factors:

Money.

Effort.

If you won't put in the effort, and you won't put in the money, then it
won't happen. Moaning that other people aren't putting in the money to
hire team of professional writers isn't productive, and moaning that
other people aren't putting in the effort to improve the docs isn't
either.

Eh? I have a computer filled with software that I put no
money or effort into, yet there it is. So clearly you are
wrong in the general sense. Before you call me a free-loading
ingratiate consider the software you use and how much of it you
have made substantive contributions to. We all have limited
time and resources and we all have to choose where to invest that
time. That some of us choose to invest it somewhere other than
Python does not deprive of of our right to point out problems
in Python when we note them.

 

[Mark Lawrence]

Hello,

I'm mailing you to kindly request, again, that you please stop
validating "r"'s disruptiveness by responding to him on
comp.lang.python. Thank you.

Carl Banks

I hereby apologise. My only feeble excuse is that my mammary glands are
getting crushed.

 

[Paul Boddie]

However, were the Python docs site to provide a wiki, along
with a mechanism to migrate suggestions developed on the wiki
into the docs, it might well be a viable (and easier because of
the wysiwyg effect) way of improving the docs.  As other have
pointed out, Postgresql, PHP, and Haskell have done so.
Now maybe there are good reasons not to do that.  But your hand-
waving is not one of them.

I think you make some good points, although I don't have time to
respond to all of them. Certainly, the documentation situation with
Python is not ideal; otherwise, people would not be complaining about
it so frequently.

I recommend going to the existing Wiki and looking at what there is
already:

http://wiki.python.org/moin/Documentation
http://wiki.python.org/moin/CategoryDocumentation

Sadly, I don't think you'll find much to work with, apart from the
occasional attempt to make an annotated version of the existing
documentation:

http://wiki.python.org/moin/PythonLibraryReference

So my next recommendation is to either use the existing Wiki
infrastructure or to ask for a separate Wiki for the purpose of
reworking the documentation. You could either take the existing
documentation, which I believe is now restructured text, and just drop
that into the Wiki with the appropriate format directives (for later
reworking in Wiki format, perhaps), or you could start afresh and
tackle some of the more serious issues head on.

I can see benefits to just starting from scratch. Perhaps the
licensing should be more explicit than the existing material on the
Wiki so that the documentation produced could be freely distributed
without uncertainty, but the outcome would hopefully be something that
stands on its own as an alternative or a replacement to the
conventional documentation.

Paul

 

[r]

....(Carl Banks doing what he does best)
Carl,
You have no right to tell people when where and how they should speak
to anyone. And how dare you think you can! If you spent even a
fraction of the time you spend manipulating the direction of this list
and instead, actually contributing to the problem at hand, (discussion
or otherwise) we would be much closer to solving this problem today.

You (and your conspirators) are the reason most people find the c.l.py
list so disturbing and wish not to participate. Get a life you moron
and stop trying to control the world.

PS: GET STUFFED!

 

[Chris Jones]

Hello Paul,

This is strictly OT, but when you get a chance, could you contact me off
list at the above address?

I need your help with the From: email address specified in your posts to
the list.

Thanks,

CJ

 

[Carl Banks]

Certainly, the documentation situation with
Python is not ideal; otherwise, people would not be complaining about
it so frequently.

I will not take an opinion on whether Python's documentation is ideal
(more on why below) but I will opine that the conclusion doesn't
follow from your premise. People's expectations of what documentation
should be are too different, there will always be people who aren't
pleased. IOW, there is no "ideal".

For example, kj (who started this mess of thread) complained that
pydoc didn't give exhaustive usage documentation. In contrast, I
think pydoc gives too much information. I would rather have only the
bare minimum; I don't want to pan through ten paragraphs just to see
what the fifth argument is.

So who's right?

No one, there is no "right". Unfortunately some people can't or won't
respect that opinions differ; they have to take perceived defects in
the docs personally.


Carl Banks

 

[exarkun]

I will not take an opinion on whether Python's documentation is ideal
(more on why below) but I will opine that the conclusion doesn't
follow from your premise. People's expectations of what documentation
should be are too different, there will always be people who aren't
pleased. IOW, there is no "ideal".

For example, kj (who started this mess of thread) complained that
pydoc didn't give exhaustive usage documentation. In contrast, I
think pydoc gives too much information. I would rather have only the
bare minimum; I don't want to pan through ten paragraphs just to see
what the fifth argument is.

So who's right?

No one, there is no "right". Unfortunately some people can't or won't
respect that opinions differ; they have to take perceived defects in
the docs personally.

This is right on. Excellent point, Carl.

Jean-Paul

 

[rurpy]

As I pointed out a few minutes ago thicko, the new version has been
available for months.

Now hold on here...

I too was bitten by this. I thought the chm docs were so unusable
that I went to the issue tracker, extremely annoyed, to submit a
rather caustic bug report. Only after looking through the doc bugs
did I find that it was already recognised, that a corrected chm
file was available, and that there were no plans to do any more
than that. (This is from memory since the python tracker is down).

On the main download page is a link to the 2.6.2 msi file with not
a word about the help file. Only if you follow the "python-2.6.2"
link to a second page, is there a link to the corrected help file,
and even that says only, "Updated Windows help file" with no
indication that it is supposed to replace a broken one in the
distribution.

If "r" is a "thicko", I'd say the handling of this issue was done
by some who are considerably thicker.

It may also be yet another example of how documentation (using
the word loosely) is produced without sufficient attention to its
usefulness to its intended audience.

 

[rurpy]

However, were the Python docs site to provide a wiki, along
with a mechanism to migrate suggestions developed on the wiki
into the docs, it might well be a viable (and easier because of
the wysiwyg effect) way of improving the docs.  As other have
pointed out, Postgresql, PHP, and Haskell have done so.
Now maybe there are good reasons not to do that.  But your hand-
waving is not one of them.

[...]
I can see benefits to just starting from scratch. Perhaps the
licensing should be more explicit than the existing material on the
Wiki so that the documentation produced could be freely distributed
without uncertainty, but the outcome would hopefully be something that
stands on its own as an alternative or a replacement to the
conventional documentation.

A couple years ago I actually did give a half-assed try to rewriting
the doc. I got the doc source downloaded and buildable with the
intent
of rewriting in bits and pieces as I had occasion to use (and find
problems with) various parts. Not knowing latex, I stupidly got side-
tracked trying to convert it to docbook which I was more interested
in.
After I gave up on that and went back to latex, I found merging
changes
from Python into my source (a little of which was heavily modified by
this time) to be very time consuming. And eventually the Python side
was changed to REST putting an end to my effort which by that time
were already pretty minimal. I concluded that the rewrite I was
trying
to do was comparable to writing a Python book, and too ambitious for
one person working on it <5 hrs/week.

And of course I am not any better writer (probably worse) than the
average Python programmer. Which is the problem with using a wiki --
unless good writers contribute, I see no reason to expect much
better results than already exist. But maybe I am too pessimistic...

 

[Paul Rubin]

On> For example, kj (who started this mess of thread) complained that
pydoc didn't give exhaustive usage documentation. In contrast, I
think pydoc gives too much information. I would rather have only the
bare minimum; I don't want to pan through ten paragraphs just to see
what the fifth argument is.

The problem is that it doesn't sufficiently separate the carefully
written useful stuff from the automatically generated useless stuff.