Issue 12047: Expand the style guide.

This commit is contained in:
Raymond Hettinger 2011-05-10 00:39:02 -07:00
parent b1241f9619
commit 351761236a
1 changed files with 104 additions and 0 deletions

View File

@ -65,6 +65,110 @@ Unix
The name of the operating system developed at AT&T Bell Labs in the early
1970s.
Affirmative Tone
----------------
The documentation focuses on affirmatively stating what the language does and
how to use it effectively.
Except for certain security risks or segfault risks, the docs should avoid
wording along the lines of "feature x is dangerous" or "experts only". These
kinds of value judgments belong in external blogs and wikis, not in the core
documentation.
Bad example (creating worry in the mind of a reader):
Warning: failing to explicitly close a file could result in lost data or
excessive resource consumption. Never rely on reference counting to
automatically close a file.
Good example (establishing confident knowledge in the effective use of the language):
A best practice for using files is use a try/finally pair to explicitly
close a file after it is used. Alternatively, using a with-statement can
achieve the same effect. This assures that files are flushed and file
descriptor resources are released in a timely manner.
Economy of Expression
---------------------
More documentation is not necessarily better documentation. Error on the side
of being succinct.
It is an unfortunate fact that making documentation longer can be an impediment
to understanding and can result in even more ways to misread or misinterpret the
text. Long descriptions full of corner cases and caveats can create the
impression that a function is more complex or harder to use than it actually is.
The documentation for :func:`super` is an example of where a good deal of
information was condensed into a few short paragraphs. Discussion of
:func:`super` could have filled a chapter in a book, but it is often easier to
grasp a terse description than a lengthy narrative.
Code Examples
-------------
Short code examples can be a useful adjunct to understanding. Readers can often
grasp a simple example more quickly than they can digest a formal description in
prose.
People learn faster with concrete, motivating examples that match the context of
a typical use case. For instance, the :func:`str.rpartition` method is better
demonstrated with an example splitting the domain from a URL than it would be
with an example of removing the last word from a line of Monty Python dialog.
The ellipsis for the :attr:`sys.ps2` secondary interpreter prompt should only be
used sparingly, where it is necessary to clearly differentiate between input
lines and output lines. Besides contributing visual clutter, it makes it
difficult for readers to cut-and-paste examples so they can experiment with
variations.
Code Equivalents
----------------
Giving pure Python code equivalents (or approximate equivalents) can be a useful
adjunct to a prose description. A documenter should carefully weigh whether the
code equivalent adds value.
A good example is the code equivalent for :func:`all`. The short 4-line code
equivalent is easily digested; it re-emphasizes the early-out behavior; and it
clarifies the handling of the corner-case where the iterable is empty. In
addition, it serves as a model for people wanting to implement a commonly
requested alternative where :func:`all` would return the specific object
evaluating to False whenever the function terminates early.
A more questionable example is the code for :func:`itertools.groupby`. Its code
equivalent borders on being too complex to be a quick aid to understanding.
Despite its complexity, the code equivalent was kept because it serves as a
model to alternative implementations and because the operation of the "grouper"
is more easily shown in code than in English prose.
An example of when not to use a code equivalent is for the :func:`oct` function.
The exact steps in converting a number to octal doesn't add value for a user
trying to learn what the function does.
Audience
--------
The tone of the tutorial (and all the docs) needs to be respectful of the
reader's intelligence. Don't presume that the readers are stupid. Lay out the
relevant information, show motivating use cases, provide glossary links, and do
our best to connect-the-dots, but don't talk down to them or waste their time.
The tutorial is meant for newcomers, many of whom will be using the tutorial to
evaluate the language as a whole. The experience needs to be positive and not
leave the reader with worries that something bad will happen if they make a
misstep. The tutorial serves as guide for intelligent and curious readers,
saving details for the how-to guides and other sources.
Be careful accepting requests for documentation changes from the rare but vocal
category of reader who is looking for vindication for one of their programming
errors ("I made a mistake, therefore the docs must be wrong ..."). Typically,
the documentation wasn't consulted until after the error was made. It is
unfortunate, but typically no documentation edit would have saved the user from
making false assumptions about the language ("I was surprised by ...").
.. _Apple Publications Style Guide: http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf