On 20/11/2014 23:10, Grant Edwards wrote:
On 2014-11-20, jstnms...@gmail.com <jstnms...@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
--
https://mail.python.org/mailman/listinfo/python-list
