Groups > comp.lang.python > #39945 > unrolled thread

Do you feel bad because of the Python docs?

Started by	Steven D'Aprano <steve+comp.lang.python@pearwood.info>
First post	2013-02-26 12:54 +0000
Last post	2013-03-04 08:59 -0800
Articles	20 on this page of 89 — 30 participants

Back to article view | Back to comp.lang.python

  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

Page 4 of 5 — ← Prev page 1 2 3 [4] 5 Next page →

#39987

From	Terry Reedy <tjreedy@udel.edu>
Date	2013-02-26 13:43 -0500
Message-ID	<mailman.2563.1361904255.2939.python-list@python.org>
In reply to	#39945

On 2/26/2013 7: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/

To me, this is a lying troll rant worth less than most of RantingRick's 
posts.

> It is valuable to contrast and compare the PHP and Python docs:
>
> http://php.net/manual/en/index.php
> http://www.python.org/doc/

The contrast has been discussed before on python-list and even pydev. To 
repeat: in my opinion, and that of most core developers, the python docs 
are superior. It is Joe's lie to equate difference of opinion with 
indifference.

Python has a nice Tutorial for beginners. It is an integral part of the 
doc set. To ignore that (and the indexes) in discussing the usability of 
Python docs by beginners is to lie. (If beginners who actually read the 
tutorial have problems with particular paragraphs, improvements can be 
and have been made.)

Examples: Once startup is explained, the rest of the tutorial is about 
half text and half example. I think that is a good balance. Anyone who 
reads the tutorial knows how to call a function. I think doubling the 
size of the Library *Reference* with trivial, repetitive examples like:

 >>> len([1,2,3])
3

would be a negative for reference use*. Python has a super-duper 
interactive mode for trying things like this oneself, and that teaches 
*better* than just reading the same thing. (And if the tutorial never 
discusses len() and its generic use for all concrete collections, it 
should.)

* Anyone who disagrees can go to
http://www.lightbird.net/py-by-example/builtin-functions.html
where you can find that and other examples for builtins and about 30 
modules. Actually, I can imagine that some beginners would benefit from 
this page as an extension of the tutorial. This site may be an outcome 
of the previous discussion, which more or less ended with the fact that 
anyone who wanted to produce php-style Python docs was free to do so.

Searching: it is true that the Python docs are written for being read by 
people, rather than by search engines#. It has a hand-crafted index 
(yes, it still needs patches) that will get you most places, especially 
for anyone who has read the tutorial to get the basics. For 'length of a 
list' one can find 'len() (built-in function)' and find that 'len' 
indeed mean length and, more generally, size.

# Anyone who wants to could develop an seo-optimized python-by-function 
website that goes into exquisite details for each function on a separate 
page.

len(collection) => count
Built-in function len() allows one to find the
* length or size of a list
* length or size of a tuple
* length or size of an array
* length or size of a string
* length or size of a bytes
* length or size of a bytearray
* length or size of a memoryview
* size of a set
* size of a frozenset
* size of a dict or dictionary
* size of dict view
* size of user-defined collecton class instances

Returns 0 for empty collections. Raises TypeError for inputs that are 
not collections or that do not support len() calls, because they do not 
have a properly written .__len__ methods.

If I were involved, I would *not* junk-up such pages with random user 
posts. Anything worth being added should be incorporated into the entry 
itself.

-- 
Terry Jan Reedy

[toc] | [prev] | [next] | [standalone]

#40090

From	rurpy@yahoo.com
Date	2013-02-27 17:17 -0800
Message-ID	<a04eb5ff-9190-40ac-9051-28c220baa252@googlegroups.com>
In reply to	#39987

On 02/26/2013 11:43 AM, Terry Reedy wrote:
> On 2/26/2013 7: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/

In which JoePie91 writes:
  ...the community around Python is one of the most hostile and
  unhelpful communities around any programming-related topic that
  I have ever seen...

> To me, this is a lying troll rant worth less than most of RantingRick's 
> posts.

Rather making his point, aren't you?

>[...]

[toc] | [prev] | [next] | [standalone]

#40092

From	Mark Lawrence <breamoreboy@yahoo.co.uk>
Date	2013-02-28 01:39 +0000
Message-ID	<mailman.2632.1362015458.2939.python-list@python.org>
In reply to	#40090

On 28/02/2013 01:17, rurpy@yahoo.com wrote:
> On 02/26/2013 11:43 AM, Terry Reedy wrote:
>> On 2/26/2013 7: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/
>
> In which JoePie91 writes:
>    ...the community around Python is one of the most hostile and
>    unhelpful communities around any programming-related topic that
>    I have ever seen...
>
>> To me, this is a lying troll rant worth less than most of RantingRick's
>> posts.
>
> Rather making his point, aren't you?
>
>> [...]

No.

-- 
Cheers.

Mark Lawrence

[toc] | [prev] | [next] | [standalone]

#40097

From	Terry Reedy <tjreedy@udel.edu>
Date	2013-02-27 21:27 -0500
Message-ID	<mailman.2634.1362018468.2939.python-list@python.org>
In reply to	#40090

On 2/27/2013 8:17 PM, rurpy@yahoo.com wrote:
> On 02/26/2013 11:43 AM, Terry Reedy wrote:

> In which JoePie91 writes:
>    ...the community around Python is one of the most hostile and
>    unhelpful communities around any programming-related topic that
>    I have ever seen...
>
>> To me, this is a lying troll rant worth less than most of RantingRick's
>> posts.
>
> Rather making his point, aren't you?

Not at all. Over the past 15 years I have make 1000s of polite helpful 
responses to perhaps 100s of different people. Others have done much the 
same. The fact that I am hostile to and occasionally make an exception 
to not responding to lying troll rants does not at all prove his lie. 
Indeed, Joe did not post here, and I was not speaking to him. I intended 
my complete post to be overall helpful to people who do read here. If 
Joe ever does post a polite question here, I hope and expect he would 
get a polite response.

-- 
Terry Jan Reedy

[toc] | [prev] | [next] | [standalone]

#39990

From	Mitya Sirenef <msirenef@lightbird.net>
Date	2013-02-26 13:58 -0500
Message-ID	<mailman.2566.1361905144.2939.python-list@python.org>
In reply to	#39945

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

[toc] | [prev] | [next] | [standalone]

#40002

From	rh <richard_hubbe11@lavabit.com>
Date	2013-02-26 12:18 -0800
Message-ID	<mailman.2572.1361909862.2939.python-list@python.org>
In reply to	#39945

On 26 Feb 2013 12:54:56 GMT
Steven D'Aprano <steve+comp.lang.python@pearwood.info> 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".

No I do not feel bad.
I did not read the post either.

As a newcomer to python I found the docs to be difficult.
I'm getting used to reading them after a few months.
Any document is written for some audience, maybe
python needs to target wider audience groups. One for programmers
from other languages (maybe one for each major language?).
One for those new to programming and python at the same time.
One for python programmers (have mostly that now, I think)
Etc.

If I harken back to those days when I first used man pages
it was a moment of "Wow! This is great!" followed by many
moments of "Hmmmm, do they mean this...?". 

Incorrect docs are worse than none. I think most of the python docs
I've read have been correct although sometimes stuff is just missing.
Like threading.local was not easy to find.

HTMLParser is avoided by lots of people because it requires lots
of prior knowledge.

Examples are worth more then plain old doc.

[toc] | [prev] | [next] | [standalone]

#40008

From	Rotwang <sg552@hotmail.co.uk>
Date	2013-02-26 21:26 +0000
Message-ID	<kgj97t$in6$1@dont-email.me>
In reply to	#39945

On 26/02/2013 12:54, 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 strongly disagree with most of what the author writes. To start with, 
there's this:

   Let’s start out with a simple example. Say you are a developer that
   just started using PHP, and you want to know how to get the current
   length of an array. You fire up a browser and Google for “PHP array
   length site:php.net”. The first result is spot-on, and one minute
   later, you know that count($arr) will suffice.

   Now let’s say that you wish to do the same in Python. In this case,
   you would Google for “Python list length site:docs.python.org”, and
   the first result is… a page with several chapters on standard types?

It seems to me that this is /completely/ the wrong way for a developer 
who's new to Python to go about learning the language. If you don't know 
enough Python to be familiar with len(), the sensible thing to is not to 
try coding by finding out individual language features as and when you 
need them, but to read the tutorial, systematically from start to 
finish. This list is continually being bombarded with questions from 
people who tried the former only to become stuck when something didn't 
work the way they thought it should (I've been guilty of this too), 
because knowing vocabulary is not the same thing as knowing how a 
language works. The majority of such questions could have been answered 
by simply reading the tutorial. More still could be answered by reading 
the language reference, which really isn't very long.

That's not to say that experienced users don't need to look things up, 
but then why would one restrict a web search to docs.python.org? Almost 
every question I've had about how to do something in Python has already 
been asked at StackExchange, and Google will find it.

   When you Google for something, you will end up on a page that
   explains a lot of things, including what you’re looking for. But how
   are you supposed to know where on the page it is, or whether it’s
   even on the page at all? The problem here is that the particular
   operation you are trying to find documentation on, does not have its
   own page.

And the solution is Ctrl-f.

   The general norm for the Python community appears to be that if you
   are not already familiar with the language, you do not deserve help.
   If you do something in a less-than-optimal way, other Python
   developers will shout about how horrible you are without bothering to
   explain much about what you did wrong. When you ask out of curiosity
   how a certain thing works, and that thing is considered a bad
   practice, you will get flamed like there’s no tomorrow – even if you
   had no intention of ever implementing it.

This is not my experience at all. Even when asking questions that I 
could have answered myself if I had RTFM, I've received helpful advice 
and nothing that could be construed as a flame. I don't know how this 
compares to other programming language communities, but it's much 
friendlier to newcomers here than, say, sci.math (whose competent 
regulars are understandably suspicious of people asking idiotic 
questions, given how many of those people turn out to be cranks).

   PHP solves [ambiguity] by having examples for every single function
   and class. If you’re not sure what is meant with a certain sentence in
   the description, you just look at one of the included examples, and
   all ambiguity is removed. It’s immediately obvious how to use things.

Python solves this by having an interactive interpreter. The tutorial 
goes to the trouble of pointing out that "[i]t helps to have a Python 
interpreter handy for hands-on experience".

   If you are an experienced developer, then you are most likely in a
   very bad position to judge how beginner-friendly the documentation
   for a language is.

   [...]

   Most of all, accept that your personal experiences with Python, as an
   experienced developer, are not worth very much. Listen to the newbies
   when they tell you the documentation is hard to read or find stuff in.

But I'm not an experienced developer. I'm an amateur hobbyist who came 
to learn Python having only had any real programming experience with BBC 
BASIC and OPL (both as a child). I read the tutorial, then I read the 
language reference, now I'm reading the library reference. They're all fine.

-- 
I have made a thing that superficially resembles music:

http://soundcloud.com/eroneity/we-berated-our-own-crapiness

[toc] | [prev] | [next] | [standalone]

#40010

From	Jason Swails <jason.swails@gmail.com>
Date	2013-02-26 17:17 -0500
Message-ID	<mailman.2578.1361917045.2939.python-list@python.org>
In reply to	#40008

[Multipart message — attachments visible in raw view] — view raw

Just to throw in my 2c -- in the same way that 'a picture is worth a
thousand words', an interactive interpreter is worth volumes of
documentation (especially one with such a nice help()/__doc__
functionality).  It's worth pointing out that 'interpreter' appears in the
original rant once (according to ctrl-F, whole thing was tl;dr):

Want to know how the Python interpreter deals with input Y? Read the
source. And so on, and so on.

Not: "Open up an interpreter and input Y"

You aren't sure what errors are thrown by a particular function?  Fire up
an interpreter and feed the function junk.  You'll get your answer faster
than you can Google, and often learn neat stuff along the way. (I recall
one of RR's posts that actually had some good tips to
learn-via-interpreter).

Also, I'll bet the way I learned Python effectively would seem like
nails-on-a-chalkboard to others -- and vice versa.  The 'one-size-fits-all'
doesn't work for documentation.  Complete and concise often battle, with no
clear winner.

And his representation of the Python community does not appear to be
representative of my experience (threads begun via trolling rants
notwithstanding).  But he's ranting on his blog; not a big deal really.

--Jason

[toc] | [prev] | [next] | [standalone]

#40018

From	Rick Johnson <rantingrickjohnson@gmail.com>
Date	2013-02-26 17:22 -0800
Message-ID	<81f2a980-a5b3-4ccc-b383-6663918afd8a@googlegroups.com>
In reply to	#40010

On Tuesday, February 26, 2013 4:17:22 PM UTC-6, Jason Swails wrote:
> Just to throw in my 2c -- in the same way that 'a picture
> is worth a thousand words', an interactive interpreter is
> worth volumes of documentation (especially one with such a
> nice help()/__doc__ functionality).

Yes! I don't even know why people care about the Python docs anyway. One of the most under-appreciated (and maybe even unknown) aspects of the Python language is the power of doc strings and the help function. Not to mention the awesome introspection capabilities via a few built-in functions:

    id(obj)
    isinstance(obj, type)
    issubclass(obj, klass)
    repr(obj)
    type(obj)
    bool(obj)
    dir(obj)
    ...

As for the docs: 

I would say that if you are searching for a "particular something" (and the help function has failed you), then skip the docs and use Google instead. The docs only seem to work well when read in a "linear" fashion; with exception of the "global module index" and the "language reference" sections.

As for the "official tutorial", do yourself a favor and DON'T read it (or never read it) until AFTER you are comfortable with python. It's not so much that the tutorial is lacking, it's more that the tutorial uses poor example code and as such is an abomination. That's my opinion anyway. There are tons of great python tutorials on the web.

> You aren't sure what errors are thrown by a particular
> function?  Fire up an interpreter and feed the function
> junk.  You'll get your answer faster than you can Google,
> and often learn neat stuff along the way. 

Yes! Interactive sessions are what make python so damn great! If you don't have an editor window and a shell window open when writing (python) code, you are doing something wrong.

> (I recall one of
> RR's posts that actually had some good tips to learn-via-
> interpreter).

I don't remember the exact thread off-hand, but i must admit you can find loads of great information in my threads! :-P

[toc] | [prev] | [next] | [standalone]

#40024

From	Rick Johnson <rantingrickjohnson@gmail.com>
Date	2013-02-26 17:22 -0800
Message-ID	<mailman.2589.1361933408.2939.python-list@python.org>
In reply to	#40010

On Tuesday, February 26, 2013 4:17:22 PM UTC-6, Jason Swails wrote:
> Just to throw in my 2c -- in the same way that 'a picture
> is worth a thousand words', an interactive interpreter is
> worth volumes of documentation (especially one with such a
> nice help()/__doc__ functionality).

Yes! I don't even know why people care about the Python docs anyway. One of the most under-appreciated (and maybe even unknown) aspects of the Python language is the power of doc strings and the help function. Not to mention the awesome introspection capabilities via a few built-in functions:

    id(obj)
    isinstance(obj, type)
    issubclass(obj, klass)
    repr(obj)
    type(obj)
    bool(obj)
    dir(obj)
    ...

As for the docs: 

I would say that if you are searching for a "particular something" (and the help function has failed you), then skip the docs and use Google instead. The docs only seem to work well when read in a "linear" fashion; with exception of the "global module index" and the "language reference" sections.

As for the "official tutorial", do yourself a favor and DON'T read it (or never read it) until AFTER you are comfortable with python. It's not so much that the tutorial is lacking, it's more that the tutorial uses poor example code and as such is an abomination. That's my opinion anyway. There are tons of great python tutorials on the web.

> You aren't sure what errors are thrown by a particular
> function?  Fire up an interpreter and feed the function
> junk.  You'll get your answer faster than you can Google,
> and often learn neat stuff along the way. 

Yes! Interactive sessions are what make python so damn great! If you don't have an editor window and a shell window open when writing (python) code, you are doing something wrong.

> (I recall one of
> RR's posts that actually had some good tips to learn-via-
> interpreter).

I don't remember the exact thread off-hand, but i must admit you can find loads of great information in my threads! :-P

[toc] | [prev] | [next] | [standalone]

#40017

From	Mark Janssen <dreamingforward@gmail.com>
Date	2013-02-26 17:15 -0800
Message-ID	<mailman.2583.1361927712.2939.python-list@python.org>
In reply to	#39945

[Multipart message — attachments visible in raw view] — view raw

On Tue, Feb 26, 2013 at 4:54 AM, Steven D'Aprano <
steve+comp.lang.python@pearwood.info> wrote:

> 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 so at all.  I think the python docs are quite well organized.
 Who googles for python knowledge when you can just go to the official site
and use the doc search?

Mark

[toc] | [prev] | [next] | [standalone]

#40019

From	Chris Angelico <rosuav@gmail.com>
Date	2013-02-27 12:31 +1100
Message-ID	<mailman.2584.1361928719.2939.python-list@python.org>
In reply to	#39945

On Wed, Feb 27, 2013 at 12:15 PM, Mark Janssen
<dreamingforward@gmail.com> wrote:
> On Tue, Feb 26, 2013 at 4:54 AM, Steven D'Aprano
> <steve+comp.lang.python@pearwood.info> wrote:
>>
>> 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 so at all.  I think the python docs are quite well organized.
> Who googles for python knowledge when you can just go to the official site
> and use the doc search?

I'm not sure if you're trolling or not... The python.org search is one
of its weakest attributes; on the main http://python.org/ search, it's
now been replaced by a Google site-search, but the box on the side in
http://docs.python.org/ still gives the annoyingly slow internal
search. So no, I don't go to the official site search, I use Google
(with or without site:python.org to restrict the results - most often
without).

ChrisA

[toc] | [prev] | [next] | [standalone]

#40022

From	Terry Reedy <tjreedy@udel.edu>
Date	2013-02-26 21:00 -0500
Message-ID	<mailman.2587.1361930463.2939.python-list@python.org>
In reply to	#39945

On 2/26/2013 1:58 PM, Mitya Sirenef wrote:

> 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?

We are not literally going to write text like that, but we did recently 
re-organized the doc for one module specifically to put the most 
commonly used stuff (about the 'convenience' functions) at the top 
instead of buried where it was.

> 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.

In the case above, there is no duplication to be kept in sync. More the 
problem is that people working of the docs tend to either leave or move 
on to code. Report like 'This section is unclear' are not too helpful 
either.

-- 
Terry Jan Reedy

[toc] | [prev] | [next] | [standalone]

#40023

From	rh <richard_hubbe11@lavabit.com>
Date	2013-02-26 18:06 -0800
Message-ID	<mailman.2588.1361930758.2939.python-list@python.org>
In reply to	#39945

On 26 Feb 2013 12:54:56 GMT
Steven D'Aprano <steve+comp.lang.python@pearwood.info> 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/

FWIW,  I refer to the docs often. I keep a local copy and
serve the pages up locally

1. http://docs.python.org/2/archives/python-2.7.3-docs-html.tar.bz2
2. unroll
3. cd python-2.7.3-docs-html
4. python -c 'import SimpleHTTPServer as foo;foo.test()' 9292
5. point browser to 0:9292


> 
> 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
> 
> 
> 
> -- 
> Steven


--

[toc] | [prev] | [next] | [standalone]

#40027

From	Mitya Sirenef <msirenef@lightbird.net>
Date	2013-02-26 22:09 -0500
Message-ID	<mailman.2591.1361934557.2939.python-list@python.org>
In reply to	#39945

Subject:   Re: Do you feel bad because of the Python docs?  To:
python-list@python.org Cc:        Bcc:
-=-=-=-=-=-=-=-=-=# Don't remove this line #=-=-=-=-=-=-=-=-=- On
  02/26/2013 09:00 PM, Terry Reedy wrote:
> On 2/26/2013 1:58 PM, Mitya  Sirenef wrote:
 >
 >> 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?
 >
 > We are not literally going to write text like that, but we did
 > recently re-organized the doc for one module specifically to put the
 > most commonly used stuff (about the 'convenience' functions) at the
 > top instead of buried where it was.

Yes, I didn't mean it would be literally worded like 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.
 >
 > In the case above, there is no duplication to be kept in sync. More
 > the problem is that people working of the docs tend to either leave or
 > move on to code. Report like 'This section is unclear' are not too
 > helpful either.
 >

I don't think that would work in the general case, for all modules,
because the 'inclusive' section should not be missing items that
logically belong there. For example, if I'm looking through string
formatting subsection, it would be confusing if some items were missing
because they were moved to the top together with other items from
different subsections.

In addition, the 'inclusive' section would have some advanced notes that
would not be included in the first section, even if items themselves may
be there.

For example, let's take timedelta section:

http://docs.python.org/2/library/datetime.html#timedelta-objects

At the end of this section there is a dozen lines of helpful examples.

I think vast majority of visitors need these examples (not a complete
list, just an example of examples), and it would be ideal if they were
shown at the very top of the page, without the need to scroll down:

>>> from datetime import  timedelta, datetime
 >>> three_days = timedelta(days=3)
 >>> datetime.now()
datetime.datetime(2013, 2, 26, 21, 45, 44, 371334)
>>> datetime.now() +  three_days
datetime.datetime(2013, 3, 1, 21, 45, 34, 427403)
>>> old_date =  datetime(2013, 2, 10)
 >>> if datetime.now() - old_date > timedelta(days=10):
...  print("It's been more than 10 days since %s" % old_date)
It's been more than 10 days since 2013-02-10 00:00:00
>>> year =  timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)  # adds up to 365 days
>>> year.total_seconds()
31536000.0

(As a side note, I think it would be better if sections in datetime were
in separate pages, it would be easier to google and the navbar on the
left side is very crowded and rather hard to read - often I find myself
missing stuff that's in there and ending up just scrolling down through
the document until I find what I need -- it might be better if section
numbers were not included there, font for keywords was not fixed width
font, and topics didn't wrap so much - in case of datetime, all of the
topics have enough horizontal space not to wrap and yet 3 out of 7 do wrap!)

Of course, it can be argued that these are minor issues, that relevant
parts of documentation are still quite easy to get to, and if it takes a
few minutes longer, it's not the end of the world.

In my view, such small matters are more important than it looks, because
working on a project requires focus and if you spend just a few minutes
hunting around the doc pages, you start to lose the larger picture of
your design... I tend to remember the most important modules out of
standard lib because I've worked with them a lot in the last few years,
but I imagine it can be tough for people who program a bit as a hobby or
as a small part of their job.

I don't mean to say that Python docs are terrible, though. They're quite
good, especially as more examples were added in the last few years, but
if they were split up in the 95/5 fashion as I've described, that would
be pretty great.

  -m

-- 
Lark's Tongue Guide to Python: http://lightbird.net/larks/

Life is not a spectacle or a feast; it is a predicament.  George Santayana

[toc] | [prev] | [next] | [standalone]

#40030

From	Mitya Sirenef <msirenef@lightbird.net>
Date	2013-02-26 23:45 -0500
Message-ID	<mailman.2593.1361940322.2939.python-list@python.org>
In reply to	#39945

On 02/26/2013 10:09 PM, Mitya Sirenef wrote:
> (As a side note, I think it  would be better if sections in datetime were
 > in separate pages, it would be easier to google and the navbar on the
 > left side is very crowded and rather hard to read - often I find myself
 > missing stuff that's in there and ending up just scrolling down through
 > the document until I find what I need -- it might be better if section
 > numbers were not included there, font for keywords was not fixed width
 > font, and topics didn't wrap so much - in case of datetime, all of the
 > topics have enough horizontal space not to wrap and yet 3 out of 7 do 
wrap!)

In regard to Python doc topic menu readability -- compare to the django
topic menu:

https://docs.djangoproject.com/en/dev/topics/db/queries/

It's ridiculous how much more readable it is, at least to my eyes!

  -m


-- 
Lark's Tongue Guide to Python: http://lightbird.net/larks/

[toc] | [prev] | [next] | [standalone]

#40042

From	Mark Lawrence <breamoreboy@yahoo.co.uk>
Date	2013-02-27 09:47 +0000
Message-ID	<mailman.2599.1361958444.2939.python-list@python.org>
In reply to	#39945

On 26/02/2013 12:54, 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
>

Not really when we've got world leading experts to help us out 
http://xahlee.info/perl-python/python_doc.html :) * sys.maxint

-- 
Cheers.

Mark Lawrence

[toc] | [prev] | [next] | [standalone]

#40058

From	Antoine Pitrou <solipsis@pitrou.net>
Date	2013-02-27 13:17 +0000
Message-ID	<mailman.2615.1361971060.2939.python-list@python.org>
In reply to	#39945

Steven D'Aprano <steve+comp.lang.python <at> pearwood.info> writes:
> 
> It is valuable to contrast and compare the PHP and Python docs:
> 
> http://php.net/manual/en/index.php
> http://www.python.org/doc/

I suppose you should compare it with http://docs.python.org/3/ instead.

> There's no doubt that one of PHP's strengths, perhaps its biggest 
> strength, is the good state of documentation.

My (probably outdated) experience with the PHP docs is that they are very
succinct and don't document failure cases or behavioral details at all.
Sure, if you only care about the big picture, they are good enough.

Regards

Antoine.

[toc] | [prev] | [next] | [standalone]

#40060

From	Antoine Pitrou <solipsis@pitrou.net>
Date	2013-02-27 13:22 +0000
Message-ID	<mailman.2617.1361971382.2939.python-list@python.org>
In reply to	#39945

Mitya Sirenef <msirenef <at> lightbird.net> writes:
> 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.

The 95/5 rule is generally a fallacy which ignores that the 5% which the
readers are expecting to learn about is not the same 5% from reader to reader.
(*)

Which means that in the end you would really want a diversity of HOWTOs
targeted at different usages of the stdlib. But it is a lot of work to
write *and* maintain.

(*) cf. http://www.joelonsoftware.com/items/2006/12/09.html

Regards

Antoine.

[toc] | [prev] | [next] | [standalone]

#40077

From	Rick Johnson <rantingrickjohnson@gmail.com>
Date	2013-02-27 14:59 -0800
Message-ID	<c7283d7d-5a96-4b1f-8080-e5510d6d26ca@googlegroups.com>
In reply to	#40060

On Wednesday, February 27, 2013 7:22:44 AM UTC-6, Antoine Pitrou wrote:
> Which means that in the end you would really want a diversity of HOWTOs
> targeted at different usages of the stdlib. But it is a lot of work to
> write *and* maintain.

So instead we maintain a "simple", albeit broken, doc that experienced pythonista's  prefer to read, whilst newbies loath? Is not the *target* audience noobs?

[toc] | [prev] | [next] | [standalone]

Page 4 of 5 — ← Prev page 1 2 3 [4] 5 Next page →

csiph-web

Do you feel bad because of the Python docs?

Contents

#39987

#40090

#40092

#40097

#39990

#40002

#40008

#40010

#40018

#40024

#40017

#40019

#40022

#40023

#40027

#40030

#40042

#40058

#40060

#40077