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

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

Do you feel bad because of the Python docs?

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

Contents

  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 1 of 5  [1] 2 3 4 5  Next page →

#39945 — Do you feel bad because of the Python docs?

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



-- 
Steven

[toc] | [next] | [standalone]

#39946

On Tue, Feb 26, 2013 at 11:54 PM, 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/

There are some issues with the Googleability of the Python docs at the
moment. It's much easier to find the official page of PHP's docs than
Python's. Trouble is, the official page of PHP docs is a lot less
helpful... like he says, it's in some cases flat-out wrong. And then
you go read the comments underneath in the hope of learning what you
need to know... and you find a pile of junk even worse than the main
docs, but with the occasional useful gem so you can't dismiss it out
of hand. (But it's buried among loads of code whose primary purpose is
to explain why there's so much bad PHP code out there.)

His "experiment" (name all the possible error conditions) is one that
I guarantee you will fail in EVERY language. Even in Java, where a
method has to declare every exception it might throw, makes an
exception (if you'll excuse the pun) for "runtime errors"... such as
division by zero. So if I write a function that takes two arguments,
divides one by the other, and adds three, then I don't need to declare
that it might bomb if you give it zero and zero. Will it be in the
docs? Unlikely.

The lack of examples is a valid concern. However, PHP isn't actually
that much better, because the prolific examples don't always help.
Examples are no panacea.

Final point: "NO-ONE IS FIXING THIS". I wonder how many docs patches
he's submitted, how many newbies he's courteously and competently
assisted.

The complaints about the community definitely do not apply to
python-list. So I'd say that's a fairly good fallback: if you can't
find what you need in the docs, and you've made a genuine effort to do
so, ask on c.l.p/p-l and you'll likely get a response within a day -
sometimes within the hour. (If Giacomo says he will respond within the
hour, he will respond... within the hour!)

tl;dr: Nothing's perfect but it ain't as bad as all tharrt.

ChrisA

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

#39949

In article <mailman.2541.1361884843.2939.python-list@python.org>,
 Chris Angelico <rosuav@gmail.com> wrote:

> There are some issues with the Googleability of the Python docs at the
> moment. It's much easier to find the official page of PHP's docs than
> Python's. Trouble is, the official page of PHP docs is a lot less
> helpful... like he says, it's in some cases flat-out wrong. And then
> you go read the comments underneath in the hope of learning what you
> need to know... and you find a pile of junk even worse than the main
> docs, but with the occasional useful gem so you can't dismiss it out
> of hand. (But it's buried among loads of code whose primary purpose is
> to explain why there's so much bad PHP code out there.)

Having lived through a year of PHP hell, I've developed a theory about 
the PHP ecosystem (i.e. docs, forums, user community, etc) vs. the 
Python ecosystem.

When people ask PHP questions, the questions tend to be phrased as "what 
do I type to get X", and the answers come back that way too.  The forums 
are full of, "I had the same problem.  Somebody told me to do this.  I 
don't really understand it, but it worked for me and maybe it'll work 
for you too".

The Python ecosystem is much more about understanding what's actually 
happening.

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

#39952

On Wed, Feb 27, 2013 at 12:56 AM, Roy Smith <roy@panix.com> wrote:
> When people ask PHP questions, the questions tend to be phrased as "what
> do I type to get X", and the answers come back that way too.  The forums
> are full of, "I had the same problem.  Somebody told me to do this.  I
> don't really understand it, but it worked for me and maybe it'll work
> for you too".

A problem that's majorly exacerbated by the myriad ways of doing some
things, with some of those ways deprecated and others theoretically
plausible but hopelessly impractical.

Here's an actual example that came up today at work. Suppose you have
a user-provided string that's supposed to contain a URL, and you need
to ensure that it doesn't have a trailing slash, so you can later add
"/foo" or "/bar". (Or alternatively, ensure that it DOES have a
trailing slash. Either works.) Start the timer, go find out how to do
it. Assume you are broadly familiar with PHP, and know how to do the
basics of string handling, and are competent at searching the web.
Ready? Go!

I'll wait for you to come back.

... Okay, some of you are back now. Just giving the stragglers time to
finish losing their marbles...

Alright. Here's what I found in a recreation of today's search.
Google search: php last character of string

http://php.net/manual/en/function.substr.php
-- okay, so I can use substr, but not string indexing, to find out
what the last character is
-- "Returns the extracted part of string; or FALSE on failure, or an
empty string." What kind of failures result in FALSE, and what kind in
an empty string?

http://stackoverflow.com/questions/4427172/find-last-character-in-a-string-in-php
Comment on question: "There are more than 10 ways of doing this!"
The accepted answer, fortunately, is a good one. Use rtrim. Okay.
That's nice. But look at the other answers: one mentions substr (as
above, that's half the question); one suggests the unwieldy form of
indexing from the back (with an explicit strlen); one answers
altogether the wrong question (suggesting the use of basename); and
one... suggests a regular expression. Now you have two problems.

And just to add to the pile of ways this could be done, the first
response in this thread
https://forums.digitalpoint.com/threads/how-to-get-last-character-in-string.796134/
suggests *reversing the string* and indexing from the front.

Maybe you tried different search terms and got better results, I don't
know. This wasn't the only search I did in trying to find the best way
to do this, but it was the one with the most amusing results.

The original rant specifically excluded sites like Stack Overflow as
valid sources, which in a way is fair enough. But it wasn't from
php.net that I got that information.

Okay. Now I'll try it again, for Python.
Google search: python last character of string
First result:
3.1.2 Strings
docs.python.org/release/1.5.1p1/tut/strings.html
Besides numbers, Python can also manipulate strings, which can be
expressed ... word[-1] # The last character 'A' >>> word[-2] # The
last-but-one character 'p' ...

The use of code with directly connected comments means that I can read
this part of the solution right there, without even clicking the link.
Search Engine Optimization FTW.

Searching for the second part, by adding the word 'remove' to the
search, brings up more third-party sites - for PHP:
http://www.if-not-true-then-false.com/2010/php-remove-last-character-from-string/
and for Python:
https://groups.google.com/forum/?fromgroups#!topic/comp.lang.python/TIX5u3Zhikc
http://stackoverflow.com/questions/9639754/python-remove-last-char-from-string-and-return-it

In both cases, answering the question, but not from the language's own
site. Forcing the matter with a site: search brings up poor results
for both languages. Python gives me:
http://docs.python.org/release/2.6/library/string.html
but nothing about slicing. PHP: Take your pick of functions, and I
hope you already know what they do, because the snippets don't help
you choose:
substr, rtrim, chop (which, once you go to the page, reveals itself to
be an alias for rtrim), strrpos, substr_replace, strstr

I'd have to say that, in the shoot-out, both languages died on their
own merits, but stood on the merits of third-party support. Fifteen
years ago, I would have called that a critical failure; in the 90s, I
would search for information only from official sources. But these
days, forum archives and blogs are some of the best way to find what
you need - granted, Sturgeon's Law applies, but frankly that applies
to a lot of documentation too (and Google's fairly good at helping you
find the 10%).

ChrisA

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

#39962

On Wed, 27 Feb 2013 01:26:47 +1100, Chris Angelico wrote:

> And just to add to the pile of ways this could be done, the first
> response in this thread
> https://forums.digitalpoint.com/threads/how-to-get-last-character-in-
string.796134/
> suggests *reversing the string* and indexing from the front.

Oooh, deja vu! It's like it's 1988 and I'm learning to program in 
Hypertalk all over again!



-- 
Steven

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

#39979

On 2013-02-26 14:26, Chris Angelico wrote:
> On Wed, Feb 27, 2013 at 12:56 AM, Roy Smith <roy@panix.com> wrote:
>> When people ask PHP questions, the questions tend to be phrased as "what
>> do I type to get X", and the answers come back that way too.  The forums
>> are full of, "I had the same problem.  Somebody told me to do this.  I
>> don't really understand it, but it worked for me and maybe it'll work
>> for you too".
>
> A problem that's majorly exacerbated by the myriad ways of doing some
> things, with some of those ways deprecated and others theoretically
> plausible but hopelessly impractical.
>
> Here's an actual example that came up today at work. Suppose you have
> a user-provided string that's supposed to contain a URL, and you need
> to ensure that it doesn't have a trailing slash, so you can later add
> "/foo" or "/bar". (Or alternatively, ensure that it DOES have a
> trailing slash. Either works.) Start the timer, go find out how to do
> it. Assume you are broadly familiar with PHP, and know how to do the
> basics of string handling, and are competent at searching the web.
> Ready? Go!
>
> I'll wait for you to come back.
>
> ... Okay, some of you are back now. Just giving the stragglers time to
> finish losing their marbles...
>
> Alright. Here's what I found in a recreation of today's search.
> Google search: php last character of string
>
> http://php.net/manual/en/function.substr.php
> -- okay, so I can use substr, but not string indexing, to find out
> what the last character is
> -- "Returns the extracted part of string; or FALSE on failure, or an
> empty string." What kind of failures result in FALSE, and what kind in
> an empty string?
>
[snip]
The page http://php.net/manual/en/function.substr.php says:

     Description
         string substr ( string $string , int $start [, int $length ] )

OK. It then goes on to say:

     Parameters
         string
             The input string. Must be one character or longer.

What? The input string can't be an empty string?

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

#40026

On Tue, 26 Feb 2013 17:48:27 +0000, MRAB wrote:

> On 2013-02-26 14:26, Chris Angelico wrote:
>> On Wed, Feb 27, 2013 at 12:56 AM, Roy Smith <roy@panix.com> wrote:
>>> When people ask PHP questions, the questions tend to be phrased as
>>> "what do I type to get X", and the answers come back that way too. 
>>> The forums are full of, "I had the same problem.  Somebody told me to
>>> do this.  I don't really understand it, but it worked for me and maybe
>>> it'll work for you too".
>>
>> A problem that's majorly exacerbated by the myriad ways of doing some
>> things, with some of those ways deprecated and others theoretically
>> plausible but hopelessly impractical.
>>
>> Here's an actual example that came up today at work. Suppose you have a
>> user-provided string that's supposed to contain a URL, and you need to
>> ensure that it doesn't have a trailing slash, so you can later add
>> "/foo" or "/bar". (Or alternatively, ensure that it DOES have a
>> trailing slash. Either works.) Start the timer, go find out how to do
>> it. Assume you are broadly familiar with PHP, and know how to do the
>> basics of string handling, and are competent at searching the web.
>> Ready? Go!
>>
>> I'll wait for you to come back.
>>
>> ... Okay, some of you are back now. Just giving the stragglers time to
>> finish losing their marbles...
>>
>> Alright. Here's what I found in a recreation of today's search. Google
>> search: php last character of string
>>
>> http://php.net/manual/en/function.substr.php -- okay, so I can use
>> substr, but not string indexing, to find out what the last character is
>> -- "Returns the extracted part of string; or FALSE on failure, or an
>> empty string." What kind of failures result in FALSE, and what kind in
>> an empty string?
>>
> [snip]
> The page http://php.net/manual/en/function.substr.php says:
> 
>      Description
>          string substr ( string $string , int $start [, int $length ] )
> 
> OK. It then goes on to say:
> 
>      Parameters
>          string
>              The input string. Must be one character or longer.
> 
> What? The input string can't be an empty string?

Huh, this is PHP. You're lucky it doesn't say:

"The input string. Must be one character or longer, except for the case-
insensitive string 'something-magical-happens-here'."

*wink*


-- 
Steven

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

#39950

:

On 26 February 2013 08:54, 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 [...]

> [...] should we feel bad about Python's docs?

The Python docs are my first port of call when I know the module (and
maybe the function) I want to use, but can't remember exactly how it
works. For that, and for me, they're very good.

I can also usually find the section I want if I'm answering a beginner
question on Stack Overflow and want to provide an explanatory link,
but if I weren't already familiar with the docs, I think it's quite
unlikely I'd find the relevant page easily. I agree with joepie91 that
the information on fundamental stuff is poorly organised.

> I don't think that either the Python documentation
> or community is as bad as JoePie91 suggests.

I think he has a point, albeit exaggerated, regarding the community -
or at least python-list, which is the part with which I'm familiar.
This list can be a little imposing for beginners, and its habit of
veering away from the original question into an esoteric discussion of
the language, while entertaining and educational to read for *me*,
might well end up causing OP to scratch their head.

I don't think it's intended, but sometimes there's also the sense that
regulars here are trying, not entirely successfully, to hide their
impatience with simple questions. I don't hang out at python-tutor, so
maybe it's better there (in which case, maybe its existence needs to
be better advertised).

I think Stack Overflow is a little better at that, possibly because
the rep system there encourages "grinding" in the MMORPG sense, and
easy questions get a bunch of people piling on with answers almost
instantaneously.

 -[]z.

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

#39951

On Tue, Feb 26, 2013 at 7: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 that either the Python documentation
> or community is as bad as JoePie91 suggests.

Who's we? As a user of Python I feel no responsibility for the state
of Python's documentation ;)

Do I feel like it could be improved? Sure. I've never understood why
Python doesn't document information about possible errors inside the
function documentations. Instead, you have to read the exception
documentation to find out when it might be raised, and then the exact
error conditions aren't always clearly specified at all.

My understanding from talking to members of the development team has
been that this is by design, so I've of course never submitted a
patch.

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

I'm an op in #python. If you can provide logs or a nickname I could
look into this with whoever banned you (if the ban hasn't expired
already!) However, you should appreciate that, having only been there
for three minutes, you may not have understood the expectations
#python sets on tone or subject matter. It is markedly more strict
than comp.lang.python. Also, bans aren't explained (except possibly in
the kickban message, but that's rare) unless you ask about them. It's
very easy to infer a reason from context, explanations take time (if
you explain before the ban), and PMs to a just-banned person never go
well (if you explain after the ban).


As to whether or not JoePie91's observations are correct for
#python... all the observations would apply to #python except for the
ostrich and source-reading complaints, albeit viewed through a very
negative light. I would disagree with his explanations for the reasons
for things, and his ranking of the importance of things.

IMHO the most important flaw in #python is that it's unwelcoming to
new programmers, but I can't think of a decent way to fix that.
Tutoring new programmers takes a huge amount of time. At the moment I
figure that the best we can hope to do is identify them before we
confuse the hell out of them by telling them to use classes,
generators, higher order functions, and other intermediate to advanced
topics. Unfortunately, we're not good at this. (Yet? :)


By the way, interestingly enough, JoePie91 was in #python discussing
his blog post for a bit. It was a fun conversation.

-- Devin

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

#39964

On 2013-02-26, Steven D'Aprano <steve+comp.lang.python@pearwood.info> wrote:

> "The Python documentation is bad, and you should feel bad".

Ahh!  A point at which I can interject.

As a rank green python noob, I definitely hava an opinion on python
documentation and it's not entirely flattering.  OTOH, it's hard to
toss any other single linux based documentation up as a sterling
example.  IOW, I've seen worse.  How am I learning about python?

Several sources.  The "Non-Programmer's Tutorial" docs from wikibooks
was a false start.  It goes for about 2 pages before I realized
they've snuck in some python syntax without explaining it.  So, I jump
over to "The Python Tutorial", which immediately leaves me submerged,
as it's waaay over my clueless head.  I flounder around and
desperately grab onto "Basic Python" over at About.com.  Finally, I'm
rescued!

Whoda thunk it?  I usta despise About.com.  But, they've matured
greatly since their early days.  I'm not a programmer.  In fact I
really dislike programming.  But, as a long time linux user, I really
need to learn a useful higher language.  And here is this website that
takes me by the hand and speaks to me like what I am.  Dumb as a post
and disinterested.  But, they are patient.  They explain basic
programming concepts before launching into specifics.  When they do
get specific, they use simple examples that make sense.  The don't
toss in syntax they haven't fully explained.  Great site and the one
I'm now using to progress.  I'm sure the other sites I've named will
become helpful, eventually, but now I can move forward with
confidence.

Are python doc sites perfect?  No.  I've yet to come upon anything
that clarifies why's and wherefores and the differences between the CMI
IDLE and the GUI IDLE.  And boy, are they different!  OTOH, as I said,
I've seen worse Linux docs.  BitchX or zsh?  What docs!?  Even the man
pages took me a long time to figure out.  Bluefish?  Krita?
Puh-leeze!  emacs?  It's a wonder I can use it at all.  ;)

Despite all that, I'd say python documentation is better than a poke
in the eye with a sharp stick.  I'm sure the official pages will make
more sense to me when I understand more.  As it is, they jes toss out
"lc-letter" like I know what they're talking about.  They explain it a
little bit, but I still hadda wiki it to get the full story.

As a person with some technical writing experience, I know how
difficult it can be.  I had to be careful about who I was writing for,
engineers or laymen.  It's the same with programming docs.  Writing
tutorials about python as if I jes came from 5 yrs as a C programmer
is not in the least bit helpful to a beginner like myself.  Sometimes,
one jes hasta hunt for the right flavor.  

nb
        

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

#39972

On 2013.02.26 10:19, notbob wrote:
>  zsh?  What docs!?
You mean other than the gigantic user manual?
http://zsh.sourceforge.net/Doc/

-- 
CPython 3.3.0 | Windows NT 6.2.9200 / FreeBSD 9.1

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

#39981

On 2013-02-26, Andrew Berg <bahamutzero8825@gmail.com> wrote:
> On 2013.02.26 10:19, notbob wrote:
>>  zsh?  What docs!?
> You mean other than the gigantic user manual?
> http://zsh.sourceforge.net/Doc/

"This document was generated by Simon Ruderich on July 24, 2012"

....'bout damn time!!  ;)

nb

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

#39982

On 2013-02-26 17:54, notbob wrote:
> >>  zsh?  What docs!?
> > You mean other than the gigantic user manual?
> > http://zsh.sourceforge.net/Doc/
> 
> "This document was generated by Simon Ruderich on July 24, 2012"
> 
> ....'bout damn time!!  ;)

Generated...from source that has been around for ages:

http://zsh.git.sourceforge.net/git/gitweb.cgi?p=zsh/zsh;a=history;f=Doc;hb=dd3b0506f99e690f521d9bf449dea47a51502cb2;pg=11

which suggests that they've been actively maintained since 1999-2000
or so.

-tkc

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

#39985

On 2013-02-26, Tim Chase <python.list@tim.thechases.com> wrote:

> which suggests that they've been actively maintained since 1999-2000
> or so.

....in various guises, dating back to the man pages.  Not all as
thorough as the latest "manual".  Perhaps I shoulda qualified usable
docs.  ;)

nb  

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

#39991

On Feb 26, 11:19 am, notbob <not...@nothome.com> wrote:
> On 2013-02-26, Steven D'Aprano <steve+comp.lang.pyt...@pearwood.info> wrote:
>
> > "The Python documentation is bad, and you should feel bad".
>
> Ahh!  A point at which I can interject.
>
> As a rank green python noob, I definitely hava an opinion on python
> documentation and it's not entirely flattering.  OTOH, it's hard to
> toss any other single linux based documentation up as a sterling
> example.  IOW, I've seen worse.  How am I learning about python?
>
> Several sources.  The "Non-Programmer's Tutorial" docs from wikibooks
> was a false start.  It goes for about 2 pages before I realized
> they've snuck in some python syntax without explaining it.  So, I jump
> over to "The Python Tutorial", which immediately leaves me submerged,
> as it's waaay over my clueless head.  I flounder around and
> desperately grab onto "Basic Python" over at About.com.  Finally, I'm
> rescued!
>
> Whoda thunk it?  I usta despise About.com.  But, they've matured
> greatly since their early days.  I'm not a programmer.  In fact I
> really dislike programming.  But, as a long time linux user, I really
> need to learn a useful higher language.  And here is this website that
> takes me by the hand and speaks to me like what I am.  Dumb as a post
> and disinterested.  But, they are patient.  They explain basic
> programming concepts before launching into specifics.  When they do
> get specific, they use simple examples that make sense.  The don't
> toss in syntax they haven't fully explained.  Great site and the one
> I'm now using to progress.  I'm sure the other sites I've named will
> become helpful, eventually, but now I can move forward with
> confidence.
>
> Are python doc sites perfect?  No.  I've yet to come upon anything
> that clarifies why's and wherefores and the differences between the CMI
> IDLE and the GUI IDLE.  And boy, are they different!  OTOH, as I said,
> I've seen worse Linux docs.  BitchX or zsh?  What docs!?  Even the man
> pages took me a long time to figure out.  Bluefish?  Krita?
> Puh-leeze!  emacs?  It's a wonder I can use it at all.  ;)
>
> Despite all that, I'd say python documentation is better than a poke
> in the eye with a sharp stick.  I'm sure the official pages will make
> more sense to me when I understand more.  As it is, they jes toss out
> "lc-letter" like I know what they're talking about.  They explain it a
> little bit, but I still hadda wiki it to get the full story.
>
> As a person with some technical writing experience, I know how
> difficult it can be.  I had to be careful about who I was writing for,
> engineers or laymen.  It's the same with programming docs.  Writing
> tutorials about python as if I jes came from 5 yrs as a C programmer
> is not in the least bit helpful to a beginner like myself.  Sometimes,
> one jes hasta hunt for the right flavor.
>
> nb

For me on the other hand. The Python tutorial has been the most useful
tutorial I have ever used. I had experience with Basic and Pascal.
Most other tutorials go too slow for me and I loose interest. The
python one just kept going and after reading the dozen pages in a
couple of hours I had enough of an idea about the language to start
doing the things I was interested in.

The only thing that confused me at first was finding functions like
"open" or "input" and string methods. I lost a bit of time searching
in the language reference until I found out that they are in the
Library reference: I didn't think of "open" as a library. But now I
have no problem; all I need is found under Library reference in
section 2 and 4 and starting with section 6. I also use the global
module index when I already have an idea what I am looking for.

What it could have is better searching capability and a way to see
more examples. Examples would clutter the documentation so maybe they
should be collapsible, but you can never have enough examples. As
Einstein said:
“Example isn't another way to teach, it is the only way to teach”
Outside of the tutorial there are not a lot of succinct examples of
more advanced uses of the different keywords and builtins. Thankfully
for the libraries there is Python Module of the Week for people that
know about it.

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

#40014

On 02/26/2013 11:00 AM, nn wrote:

 > What it could have is better searching capability and a way to see
 > more examples. Examples would clutter the documentation so maybe they
 > should be collapsible, but you can never have enough examples.

A good resource (although only covering up to v2.3) is effbot's guide to 
the standard library available at

   http://effbot.org/zone/librarybook-index.htm

It's pretty much _all_ examples.

Emile

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

#39968

I think learning a language from the documentation is an unreasonable expectation and burden for the authors.

Buy a book, take a class, they are designed to provide you with a path from start to finish in a sensible manner, the documentation in my opinion is supposed to be a reference and a refresher with an assumed level of basic fundamentals.

I'm currently taking a class in ARM assembly, the notion that I should expect to plop the thousand+ page reference manual on my desk and just "get to it" is absurd.

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

#39989

On Tue, Feb 26, 2013 at 11:38 AM, Adam W. <AWasilenko@gmail.com> wrote:
> I think learning a language from the documentation is an unreasonable expectation and burden for the authors.

That's how I learned it. The Python tutorial, together with the stdlib
reference manual, are often recommended to beginners to Python in
order to learn it. The combination of the documentation and consulting
other programmers helped me learn the language just fine.

> Buy a book, take a class, they are designed to provide you with a path from start to finish in a sensible manner, the documentation in my opinion is supposed to be a reference and a refresher with an assumed level of basic fundamentals.

I would assert it isn't very kind to those even with basic fundamentals.

For example, under precisely what circumstances does int() raise
TypeError? You won't find that under either int's documentation, or
TypeError's documentation, you have to look it up under __int__, which
is _not_ a basic fundamental. And rather than helping you along the
way, the documentation for int() actively misleads you by its
implicature that the only acceptable types are strings, ints, and
floats. And then even if you have the foresight to remember "oh yeah,
isn't there a special method for this?", you have to find the
documentation for __int__, which is itself is three quarters of the
way down this massive page:
http://docs.python.org/2/reference/datamodel.html .

-- Devin

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

#40021

On 2/26/2013 1:52 PM, Devin Jeanpierre wrote:

> I would assert it isn't very kind to those even with basic fundamentals.
>
> For example, under precisely what circumstances does int() raise
> TypeError? You won't find that under either int's documentation, or
> TypeError's documentation, you have to look it up under __int__, which
> is _not_ a basic fundamental. And rather than helping you along the
> way, the documentation for int() actively misleads you by its
> implicature that the only acceptable types are strings, ints, and
> floats. And then even if you have the foresight to remember "oh yeah,
> isn't there a special method for this?", you have to find the
> documentation for __int__, which is itself is three quarters of the
> way down this massive page:
> http://docs.python.org/2/reference/datamodel.html

Have you opened an issue, or checked for existing issue? I would be open 
to the idea that entries like that for int should not be overly type 
specific and imply that the defaults are the only possibilities.
Perhaps there should be a cross-reference to corresponding special 
methods. Perhaps that idea might be opposed. I am not sure. Perhaps 
Built-in Functions needs a bit more general explanatory text at the top.

-- 
Terry Jan Reedy

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

#40028

On Tuesday, February 26, 2013 7:48:51 PM UTC-6, Terry Reedy wrote:
> On 2/26/2013 1:52 PM, Devin Jeanpierre wrote:
> > 
> > [...snip legit complaint...]
> > 
> Have you opened an issue, or checked for existing issue? I would be open 
> to the idea that entries like that for int should not be overly type 
> specific and imply that the defaults are the only possibilities.

Terry (with all due respect), do you /really/ expect that people have the time to open an issue on the bug tracker? Do you really think that everyone who uses python even knows about the bug tracker? Do you really think that people will believe that their opinion is worthy of placing on the bug tracker? Do you really?

I think most will just end up ignoring the docs and either be forced to give up on Python or look for documentation elsewhere. Now, you could react to that truth by saying:

 "Well, who cares! The docs are the docs and if people can't grok them then too bad for them because i think they are awesome."

Sadly (in actuality) it's too bad for *you* Terry (along with the many other people who maintain docs) when you ignore the many request for changes. Remember, if people just ignore the docs because of these abominations you and everyone else are basically wasting your time maintaining the docs! Do you understand this fact?

Terry Implies: "We will write the docs how *we* see fit, and to hell with your feeble misunderstandings. You are beneath us! *We* are the anointed ones. *We* know everything!"
 
Look i know your intentions are noble, and yes my wording was a bit theatrically unfair, but this is /exactly/ how people are interpreting your intentions Terry. Please don't become a zealot. Python will never be perfect! I can assure you.

And besides, is a bug tracker /really/ the place to voice the many legitimate problems concerning python's documentation or stdlib? Forgive me, but I thought bug trackers where for tracking ,umm... well, BUGS! 

This is why i mentioned the need for an official "PyWarts" (group or list) so these folks will have a platform to voice their frustrations. A very PUBLIC and very ACCESSIBLE and very WELL KNOWN platform. Because if IS NOT all three of these things, then it IS nothing.

But you cannot just hand them a microphone and then stick your fingers in your ears. You need to /listen/ carefully and try to place yourself into their shoes. I can assure you that the Python docs, and the language itself, could use some polishing. Stop taking these complaints personally and start listening with an objective ear; please?

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

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

Back to top | Article view | comp.lang.python

csiph-web