Python docs disappointing
breamoreboy at yahoo.co.uk
Fri Nov 21 00:22:08 CET 2014
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,
> 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.
More information about the Python-list