[Python-Dev] cpython: PEP 417: Adding unittest.mock

[Nick Coghlan]

On Mon, Mar 19, 2012 at 11:19 AM, "Martin v. Löwis" <martin at v.loewis.de> wrote:
>> The commingling of extensive examples with regular docs has
>> made it difficult to lookup functionality in argparse for example.
>
> I have now come to think that this should be considered a subordinate
> use case. The primary use case of the documentation should be copy-paste
> style examples. At least, that's the feedback I always get for the
> Python documentation (typically contrasting it with the PHP
> documentation, where the specification-style portion is typically
> ignored by readers, which then move on to the user-contributed
> examples).

That's why the 3.2 logging docs are such a good model to follow. They
have *4* pieces:

- the formal API reference ("What features does logging offer?" and
"Exactly how does the X API work, again?")
- a "quick start" tutorial ("What's the bare minimum I need to know to
get started with the logging module?")
- an "advanced" tutorial ("What are some other cool things the logging
infrastructure lets me do?")
- a "cookbook" section ("How do I achieve task Y with the logging module?")

The first of those is in the standard library *reference*, with clear
pointers directly to the other 3 (which live in the "HOWTO" section of
the docs).

Different audiences have different needs. If you just want to get
something working quickly and aren't interested in understanding the
details right now, then "cargo cult programming" can be a good way to
go and "cookbook" style docs are a great resource for that. If you're
just trying to remember a precise incantation for something you
already know the module can do, then you want a formal reference that
spells out the API details. Tutorials land somewhere in between -
trying to teach people enough about the module that they can make more
effective use of both the formal API reference (when figuring things
out from scratch) and the cookbook examples (when trying to accomplish
a common task without caring too much about the details of how and why
it works).

As much as I like argparse, the existing docs don't do a great job of
advertising its capabilities, since they're currently a mixture of
tutorial-and-reference-and-cookbook that means they don't excel at
serving any of the possible audiences. (I've posted a few suggestions
on the issue tracker for specific changes I think would help improve
the situation).

The key point though is that there are multiple reasons people look up
documentation, and the appropriate structure varies based on the
reason someone is reading the docs at all.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia