Python docs disappointing

[Mark Lawrence]

On 20/11/2014 23:10, Grant Edwards wrote:
> On 2014-11-20, jstnms123 at gmail.com <jstnms123 at gmail.com> wrote:
>
>> I write this to address the criticism which targets a user's lack of
>> responsibility for the real/implied/insinuated failings of the docs.
>> As a relatively inexperienced student of programming, I am not in any
>> position to contribute/edit the documents.
>
> Wrong.  As an inexperienced user, you are _exactly_ the right person
> to contribute/edit the documents.  A documents _always_ make sense to
> the author and to somebody who already knows the information.  They
> are often not capable of seeing what's wrong.
>
> It's those who are _not_ familiar with the subject matter who can
> often make the most valuable contributions.
>
>> THAT DOES NOT, however, DENY THE CATEGORICAL STUPIDITY OF THE
>> DOCUMENTATION: .  Not only are the semantics of the editors in
>> question, but so are the syntactical and grammatical conventions,
>> too.
>
> Then send in suggestions, corrections and improvements.  Or pony up
> and actually take over maintenance of one of the documents you think
> is so bad.
>
> The authors of the documentation aren't _intentionally_ writing things
> that other people don't understand.  If you don't understand the
> documentation or think it needs to be extended/expanded, then help
> _do_ it.
>
> Just telling somebody "the document you wrote SUCKS!" is not even a
> _tiny_ bit helpful.
>

Having seen some of the garbage that turns up on the bug tracker under 
the guise of "improvements" I suggest that many people who criticize the 
docs don't take up a career as a technical author.

-- 
My fellow Pythonistas, ask not what our language can do for you, ask
what you can do for our language.

Mark Lawrence