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?

 
 
emile
Guest
Posts: n/a
 
      02-27-2013
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



 
Reply With Quote
 
 
 
 
Mark Janssen
Guest
Posts: n/a
 
      02-27-2013
On Tue, Feb 26, 2013 at 4:54 AM, Steven D'Aprano <
http://www.velocityreviews.com/forums/(E-Mail Removed)> 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

 
Reply With Quote
 
 
 
 
Rick Johnson
Guest
Posts: n/a
 
      02-27-2013
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 ofthe 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 thehelp 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 muchthat 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!
 
Reply With Quote
 
Rick Johnson
Guest
Posts: n/a
 
      02-27-2013
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 ofthe 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 thehelp 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 muchthat 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!
 
Reply With Quote
 
Chris Angelico
Guest
Posts: n/a
 
      02-27-2013
On Wed, Feb 27, 2013 at 12:15 PM, Mark Janssen
<(E-Mail Removed)> wrote:
> On Tue, Feb 26, 2013 at 4:54 AM, Steven D'Aprano
> <(E-Mail Removed)> 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 siteython.org to restrict the results - most often
without).

ChrisA
 
Reply With Quote
 
Terry Reedy
Guest
Posts: n/a
 
      02-27-2013
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

 
Reply With Quote
 
Terry Reedy
Guest
Posts: n/a
 
      02-27-2013
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

 
Reply With Quote
 
rh
Guest
Posts: n/a
 
      02-27-2013
On 26 Feb 2013 12:54:56 GMT
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/


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/py...s-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/wh...el-so-bad.html
>
>
>
> --
> Steven



--


 
Reply With Quote
 
Steven D'Aprano
Guest
Posts: n/a
 
      02-27-2013
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 <(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?


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
 
Reply With Quote
 
Mitya Sirenef
Guest
Posts: n/a
 
      02-27-2013
Subject: Re: Do you feel bad because of the Python docs? To:
(E-Mail Removed) 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/dat...edelta-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

 
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