Python docs disappointing - group effort to hire writers?

[Steven D'Aprano]

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