Do you feel bad because of the Python docs?

[Mitya Sirenef]

Subject:   Re: Do you feel bad because of the Python docs?  To:
python-list at 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