[Python-Dev] cpython: PEP 417: Adding unittest.mock (original) (raw)
Nick Coghlan ncoghlan at gmail.com
Mon Mar 19 04:24:12 CET 2012
- Previous message: [Python-Dev] cpython: PEP 417: Adding unittest.mock
- Next message: [Python-Dev] cpython: PEP 417: Adding unittest.mock
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
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
- Previous message: [Python-Dev] cpython: PEP 417: Adding unittest.mock
- Next message: [Python-Dev] cpython: PEP 417: Adding unittest.mock
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]