[Python-checkins] r70438 - python/trunk/Doc/library/functions.rst

[Raymond Hettinger]

----- Original Message ----- 
From: "Nick Coghlan" <ncoghlan at gmail.com>
To: "Raymond Hettinger" <python at rcn.com>
Cc: "benjamin.peterson" <python-checkins at python.org>
Sent: Tuesday, March 17, 2009 2:04 PM
Subject: Re: [Python-checkins] r70438 - python/trunk/Doc/library/functions.rst


> Raymond Hettinger wrote:
>> FWIW, I think the examples need to be *very* short.
>> The functions.rst page is growing hard to read because
>> of all of the lengthy examples, caveats, warnings, and
>> saying verbosity.  We don't want to turn the main docs
>> into a tutorial.  It makes them harder to use.   If someone
>> just wants to scan what the builtin functions do, they now
>> face a very lengthy page of reading.  It's getting too fat.
>> 
>> I think the example below is way too long.
> 
> Perhaps the page just needs an overview section or table at the start
> that just gives a one line description of each method, and then links to
> the more detailed descriptions with longer examples?

I did that with itertools but don't think it's a good general technique
throughout the docs.

The goal here is to make sure that we don't go down the 
slippery slope of merging the tutorial with the main docs.

This particular example has a very low information density
and it the kind of thing that goes on a docs wiki.  It is also
not a movitating example.

Contrast that with docs for _ABCs which use a table, a short
block of explanatory text and a single, succinct highly motivating
example that shows how to effectively use all of the ABCs.


Raymond