Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Do you feel bad because of the Python docs?

Reply
Thread Tools

Do you feel bad because of the Python docs?

 
 
Steven D'Aprano
Guest
Posts: n/a
 
      02-26-2013
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/0...tation-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/wh...el-so-bad.html



--
Steven
 
Reply With Quote
 
 
 
 
Chris Angelico
Guest
Posts: n/a
 
      02-26-2013
On Tue, Feb 26, 2013 at 11:54 PM, Steven D'Aprano
<(E-Mail Removed)> 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/0...tation-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
 
Reply With Quote
 
 
 
 
Roy Smith
Guest
Posts: n/a
 
      02-26-2013
In article <(E-Mail Removed)>,
Chris Angelico <(E-Mail Removed)> 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.
 
Reply With Quote
 
Zero Piraeus
Guest
Posts: n/a
 
      02-26-2013
:

On 26 February 2013 08:54, Steven D'Aprano
<(E-Mail Removed)> 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.
 
Reply With Quote
 
Chris Angelico
Guest
Posts: n/a
 
      02-26-2013
On Wed, Feb 27, 2013 at 12:56 AM, Roy Smith <(E-Mail Removed)> 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/4...-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/thre...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.co...r-from-string/
and for Python:
https://groups.google.com/forum/?fro...on/TIX5u3Zhikc
http://stackoverflow.com/questions/9...-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
 
Reply With Quote
 
Steven D'Aprano
Guest
Posts: n/a
 
      02-26-2013
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/thre...-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
 
Reply With Quote
 
notbob
Guest
Posts: n/a
 
      02-26-2013
On 2013-02-26, Steven D'Aprano <(E-Mail Removed)> 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

 
Reply With Quote
 
Adam W.
Guest
Posts: n/a
 
      02-26-2013
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.
 
Reply With Quote
 
Andrew Berg
Guest
Posts: n/a
 
      02-26-2013
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
 
Reply With Quote
 
MRAB
Guest
Posts: n/a
 
      02-26-2013
On 2013-02-26 14:26, Chris Angelico wrote:
> On Wed, Feb 27, 2013 at 12:56 AM, Roy Smith <(E-Mail Removed)> 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?

 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Re: Do you feel bad because of the Python docs? Jean-Michel Pichavant Python 0 03-01-2013 10:06 AM
What do you use java for ? AndDoes Java make you feel happy? zelzel.zsu@gmail.com Java 15 11-12-2005 03:54 AM
ActiveX apologetic Larry Seltzer... "Sun paid for malicious ActiveX code, and Firefox is bad, bad bad baad. please use ActiveX, it's secure and nice!" (ok, the last part is irony on my part) fernando.cassia@gmail.com Java 0 04-16-2005 10:05 PM
24 Season 3 Bad Bad Bad (Spoiler) nospam@nospam.com DVD Video 12 02-23-2005 03:28 AM
24 Season 3 Bad Bad Bad (Spoiler) nospam@nospam.com DVD Video 0 02-19-2005 01:10 AM



Advertisments