Python docs disappointing

Mark Lawrence breamoreboy at
Fri Nov 21 00:22:08 CET 2014

On 20/11/2014 23:10, Grant Edwards wrote:
> On 2014-11-20, jstnms123 at <jstnms123 at> 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.
>> 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

More information about the Python-list mailing list