Python docs disappointing - group effort to hire writers?

[max bianco]

On Sat, Aug 8, 2009 at 12:25 AM, Steven
D'Aprano<steve at remove-this-cybersource.com.au> wrote:
> 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.
>
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.