Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #81143

Re: Python docs disappointing

Show all headers | View raw

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

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

Re: Python docs disappointing jstnms123@gmail.com - 2014-11-20 07:54 -0800
  Re: Python docs disappointing Joel Goldstick <joel.goldstick@gmail.com> - 2014-11-20 11:51 -0500
    Re: Python docs disappointing albert@spenarnc.xs4all.nl (Albert van der Horst) - 2014-12-04 10:27 +0000
      Re: Python docs disappointing Chris Angelico <rosuav@gmail.com> - 2014-12-04 21:37 +1100
      Re: Python docs disappointing Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-12-04 22:46 +1100
      Re: Python docs disappointing jtan <admin@grails.asia> - 2014-12-05 07:33 +0800
      Re: Python docs disappointing Michael Torrie <torriem@gmail.com> - 2014-12-04 16:57 -0700
  Re: Python docs disappointing Michael Torrie <torriem@gmail.com> - 2014-11-20 09:51 -0700
  Re: Python docs disappointing Skip Montanaro <skip.montanaro@gmail.com> - 2014-11-20 11:18 -0600
  Re: Python docs disappointing Grant Edwards <invalid@invalid.invalid> - 2014-11-20 23:10 +0000
    Re: Python docs disappointing Mark Lawrence <breamoreboy@yahoo.co.uk> - 2014-11-20 23:22 +0000
  Re: Python docs disappointing Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-11-21 10:29 +1100
    Re: Python docs disappointing Grant Edwards <invalid@invalid.invalid> - 2014-11-21 16:35 +0000

csiph-web