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
--
http://mail.python.org/mailman/listinfo/python-list
