Python docs disappointing - group effort to hire writers?
steve at REMOVE-THIS-cybersource.com.au
Sat Aug 8 06:25:31 CEST 2009
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
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:
> 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"
'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).
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
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
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.
More information about the Python-list