Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.lang.python > #39990
| Date | 2013-02-26 13:58 -0500 |
|---|---|
| From | Mitya Sirenef <msirenef@lightbird.net> |
| Subject | Re: Do you feel bad because of the Python docs? |
| References | <512cb0a0$0$30001$c3e8da3$5496439d@news.astraweb.com> |
| Newsgroups | comp.lang.python |
| Message-ID | <mailman.2566.1361905144.2939.python-list@python.org> (permalink) |
On 02/26/2013 07:54 AM, Steven D'Aprano wrote: > One week ago, "JoePie91" wrote a blog post challenging the Python > community and the state of Python documentation, titled: > > "The Python documentation is bad, and you should feel bad". > > http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad- > and-you-should-feel-bad/ > > It is valuable to contrast and compare the PHP and Python docs: > > http://php.net/manual/en/index.php > http://www.python.org/doc/ > > There's no doubt that one of PHP's strengths, perhaps its biggest > strength, is the good state of documentation. But should we feel bad > about Python's docs? I don't think that either the Python documentation > or community is as bad as JoePie91 suggests. (Well, I won't speak for the > people on Freenode's #python. It took me approximately three minutes to > be banned from there, with no warning or explanation.) > > Another response to the blog post, by one of the core developers: > > http://blog.briancurtin.com/posts/why-i-dont-feel-so-bad.html > > > I think the issue with python documentation is that it ignores the 95/5 rule: 95% of people who land on a module's page are only looking for 5% of its information. So ideally it'd be separated in two different pages or two sections of the same page, something like: =============================================================================================== Hi, chances are you are the 95% of people who isn't interested in the intricacies, obscure edge cases et cetera. Here are the few common use cases for this module: ... ... ... =============================================================================================== Hi, the section above obviously did not suit your needs, so you must be in the 5% who has no choice but to either read through or at least glance through, or use search, to find what you need in the following umpteen million of screenfuls: ... * 1000000 =============================================================================================== Why doesn't Python do that? Quite simply, it's a lot more work: you have to separate most useful parts from the rest, which involves judgement calls and will cause some disagreement and ultimately won't be perfect. Once done, two separate sections need to be mainained and kept in sync. It's important that they don't contradict each other. Right now places like SO and mailing list act like the first section I described. The issue is that they're not always up to date and not guaranteed to be correct, are not in a consistent style and depth, are not centralized. -m -- Lark's Tongue Guide to Python: http://lightbird.net/larks/ Is life not a thousand times too short for us to bore ourselves? Friedrich Nietzsche
Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
Do you feel bad because of the Python docs? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2013-02-26 12:54 +0000
Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-02-27 00:20 +1100
Re: Do you feel bad because of the Python docs? Roy Smith <roy@panix.com> - 2013-02-26 08:56 -0500
Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-02-27 01:26 +1100
Re: Do you feel bad because of the Python docs? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2013-02-26 15:26 +0000
Re: Do you feel bad because of the Python docs? MRAB <python@mrabarnett.plus.com> - 2013-02-26 17:48 +0000
Re: Do you feel bad because of the Python docs? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2013-02-27 03:02 +0000
Re: Do you feel bad because of the Python docs? Zero Piraeus <schesis@gmail.com> - 2013-02-26 10:15 -0400
Re: Do you feel bad because of the Python docs? Devin Jeanpierre <jeanpierreda@gmail.com> - 2013-02-26 09:15 -0500
Re: Do you feel bad because of the Python docs? notbob <notbob@nothome.com> - 2013-02-26 16:19 +0000
Re: Do you feel bad because of the Python docs? Andrew Berg <bahamutzero8825@gmail.com> - 2013-02-26 10:55 -0600
Re: Do you feel bad because of the Python docs? notbob <notbob@nothome.com> - 2013-02-26 17:54 +0000
Re: Do you feel bad because of the Python docs? Tim Chase <python.list@tim.thechases.com> - 2013-02-26 12:10 -0600
Re: Do you feel bad because of the Python docs? notbob <notbob@nothome.com> - 2013-02-26 18:41 +0000
Re: Do you feel bad because of the Python docs? nn <pruebauno@latinmail.com> - 2013-02-26 11:00 -0800
Re: Do you feel bad because of the Python docs? emile <emile@fenx.com> - 2013-02-26 16:36 -0800
Re: Do you feel bad because of the Python docs? "Adam W." <AWasilenko@gmail.com> - 2013-02-26 08:38 -0800
Re: Do you feel bad because of the Python docs? Devin Jeanpierre <jeanpierreda@gmail.com> - 2013-02-26 13:52 -0500
Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-02-26 20:48 -0500
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-26 19:13 -0800
Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-02-27 15:25 -0800
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-27 18:05 -0800
Re: Do you feel bad because of the Python docs? Roy Smith <roy@panix.com> - 2013-02-27 21:21 -0500
Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-02-28 13:44 +1100
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-27 19:43 -0800
Re: Do you feel bad because of the Python docs? llanitedave <llanitedave@veawb.coop> - 2013-02-27 20:04 -0800
Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-02-27 20:21 -0800
Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-02-27 20:18 -0800
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-27 20:53 -0800
Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-02-27 21:57 -0800
Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-02-28 17:31 +1100
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-28 10:28 -0800
Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-03-01 07:41 +1100
Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-02-28 16:05 -0800
Re: Do you feel bad because of the Python docs? Jake Angulo <jake.angulo@gmail.com> - 2013-03-04 10:47 +1100
Re: Do you feel bad because of the Python docs? Bob Hanson <invalid@invalid.invalid> - 2013-03-05 17:43 -0800
Re: Do you feel bad because of the Python docs? Mark Lawrence <breamoreboy@yahoo.co.uk> - 2013-03-06 03:12 +0000
Re: Do you feel bad because of the Python docs? Bob Hanson <invalid@invalid.invalid> - 2013-03-08 19:10 -0800
Re: Do you feel bad because of the Python docs? Bob Hanson <invalid@invalid.invalid> - 2013-03-05 17:50 -0800
Re: Do you feel bad because of the Python docs? Bob Hanson <invalid@invalid.invalid> - 2013-03-05 17:51 -0800
Re: Do you feel bad because of the Python docs? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2013-03-06 03:38 +0000
Re: Do you feel bad because of the Python docs? Bob Hanson <invalid@invalid.invalid> - 2013-03-08 19:31 -0800
Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-03-09 14:45 +1100
Re: Do you feel bad because of the Python docs? rh <richard_hubbe11@lavabit.com> - 2013-03-06 11:48 -0800
Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-03-06 18:50 -0500
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-03-06 16:47 -0800
Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-03-06 17:06 -0800
Re: Do you feel bad because of the Python docs? Chris Kaynor <ckaynor@zindagigames.com> - 2013-03-06 17:28 -0800
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-03-06 17:31 -0800
Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-03-06 18:28 -0800
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-03-06 18:57 -0800
Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-03-06 19:12 -0800
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-03-06 19:48 -0800
Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-03-07 13:16 +1100
Re: Do you feel bad because of the Python docs? "Michael Ross" <gmx@ross.cx> - 2013-03-07 03:04 +0100
Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-03-06 20:52 -0500
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-03-06 18:41 -0800
Re: Do you feel bad because of the Python docs? Bob Hanson <invalid@invalid.invalid> - 2013-03-08 20:12 -0800
Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-03-09 01:22 -0500
Re: Do you feel bad because of the Python docs? Roy Smith <roy@panix.com> - 2013-02-27 20:26 -0500
Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-02-26 13:43 -0500
Re: Do you feel bad because of the Python docs? rurpy@yahoo.com - 2013-02-27 17:17 -0800
Re: Do you feel bad because of the Python docs? Mark Lawrence <breamoreboy@yahoo.co.uk> - 2013-02-28 01:39 +0000
Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-02-27 21:27 -0500
Re: Do you feel bad because of the Python docs? Mitya Sirenef <msirenef@lightbird.net> - 2013-02-26 13:58 -0500
Re: Do you feel bad because of the Python docs? rh <richard_hubbe11@lavabit.com> - 2013-02-26 12:18 -0800
Re: Do you feel bad because of the Python docs? Rotwang <sg552@hotmail.co.uk> - 2013-02-26 21:26 +0000
Re: Do you feel bad because of the Python docs? Jason Swails <jason.swails@gmail.com> - 2013-02-26 17:17 -0500
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-26 17:22 -0800
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-26 17:22 -0800
Re: Do you feel bad because of the Python docs? Mark Janssen <dreamingforward@gmail.com> - 2013-02-26 17:15 -0800
Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-02-27 12:31 +1100
Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-02-26 21:00 -0500
Re: Do you feel bad because of the Python docs? rh <richard_hubbe11@lavabit.com> - 2013-02-26 18:06 -0800
Re: Do you feel bad because of the Python docs? Mitya Sirenef <msirenef@lightbird.net> - 2013-02-26 22:09 -0500
Re: Do you feel bad because of the Python docs? Mitya Sirenef <msirenef@lightbird.net> - 2013-02-26 23:45 -0500
Re: Do you feel bad because of the Python docs? Mark Lawrence <breamoreboy@yahoo.co.uk> - 2013-02-27 09:47 +0000
Re: Do you feel bad because of the Python docs? Antoine Pitrou <solipsis@pitrou.net> - 2013-02-27 13:17 +0000
Re: Do you feel bad because of the Python docs? Antoine Pitrou <solipsis@pitrou.net> - 2013-02-27 13:22 +0000
Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-27 14:59 -0800
Re: Do you feel bad because of the Python docs? Mitya Sirenef <msirenef@lightbird.net> - 2013-02-27 17:43 -0500
Re: Do you feel bad because of the Python docs? rurpy@yahoo.com - 2013-02-27 15:20 -0800
Re: Do you feel bad because of the Python docs? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2013-02-28 01:05 +0000
Re: Do you feel bad because of the Python docs? rurpy@yahoo.com - 2013-02-27 21:36 -0800
Re: Do you feel bad because of the Python docs? llanitedave <llanitedave@veawb.coop> - 2013-02-27 18:26 -0800
Re: Do you feel bad because of the Python docs? Jason Friedman <jsf80238@gmail.com> - 2013-02-27 21:59 -0700
Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-02-28 16:21 +1100
Re: Do you feel bad because of the Python docs? << No! Tony the Tiger <tony@tiger.invalid> - 2013-03-03 16:28 -0600
Re: Do you feel bad because of the Python docs? rh <richard_hubbe11@lavabit.com> - 2013-03-04 08:59 -0800
csiph-web