merge

Doc/documenting/style.rst

@@ -109,6 +109,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