| .. highlightlang:: rest |
| |
| Style guide |
| =========== |
| |
| The Python documentation should follow the `Apple Publications Style Guide`_ |
| wherever possible. This particular style guide was selected mostly because it |
| seems reasonable and is easy to get online. |
| |
| Topics which are either not covered in Apple's style guide or treated |
| differently in Python documentation will be discussed in this |
| document. |
| |
| Use of whitespace |
| ----------------- |
| |
| All reST files use an indentation of 3 spaces. The maximum line length is 80 |
| characters for normal text, but tables, deeply indented code samples and long |
| links may extend beyond that. |
| |
| Make generous use of blank lines where applicable; they help grouping things |
| together. |
| |
| A sentence-ending period may be followed by one or two spaces; while reST |
| ignores the second space, it is customarily put in by some users, for example |
| to aid Emacs' auto-fill mode. |
| |
| Footnotes |
| --------- |
| |
| Footnotes are generally discouraged, though they may be used when they are the |
| best way to present specific information. When a footnote reference is added at |
| the end of the sentence, it should follow the sentence-ending punctuation. The |
| reST markup should appear something like this:: |
| |
| This sentence has a footnote reference. [#]_ This is the next sentence. |
| |
| Footnotes should be gathered at the end of a file, or if the file is very long, |
| at the end of a section. The docutils will automatically create backlinks to |
| the footnote reference. |
| |
| Footnotes may appear in the middle of sentences where appropriate. |
| |
| Capitalization |
| -------------- |
| |
| .. sidebar:: Sentence case |
| |
| Sentence case is a set of capitalization rules used in English |
| sentences: the first word is always capitalized and other words are |
| only capitalized if there is a specific rule requiring it. |
| |
| Apple style guide recommends the use of title case in section titles. |
| However, rules for which words should be capitalized in title case |
| vary greaty between publications. |
| |
| In Python documentation, use of sentence case in section titles is |
| preferable, but consistency within a unit is more important than |
| following this rule. If you add a section to the chapter where most |
| sections are in title case you can either convert all titles to |
| sentence case or use the dominant style in the new section title. |
| |
| Sentences that start with a word for which specific rules require |
| starting it with a lower case letter should be avoided in titles and |
| elsewhere. |
| |
| .. note:: |
| |
| Sections that describe a library module often have titles in the |
| form of "modulename --- Short description of the module." In this |
| case, the description should be capitalized as a stand-alone |
| sentence. |
| |
| Many special names are used in the Python documentation, including the names of |
| operating systems, programming languages, standards bodies, and the like. Most |
| of these entities are not assigned any special markup, but the preferred |
| spellings are given here to aid authors in maintaining the consistency of |
| presentation in the Python documentation. |
| |
| Other terms and words deserve special mention as well; these conventions should |
| be used to ensure consistency throughout the documentation: |
| |
| CPU |
| For "central processing unit." Many style guides say this should be |
| spelled out on the first use (and if you must use it, do so!). For |
| the Python documentation, this abbreviation should be avoided since |
| there's no reasonable way to predict which occurrence will be the |
| first seen by the reader. It is better to use the word "processor" |
| instead. |
| |
| POSIX |
| The name assigned to a particular group of standards. This is always |
| uppercase. |
| |
| Python |
| The name of our favorite programming language is always capitalized. |
| |
| reST |
| For "reStructuredText," an easy to read, plaintext markup syntax |
| used to produce Python documentation. When spelled out, it is |
| always one word and both forms start with a lower case 'r'. |
| |
| Unicode |
| The name of a character coding system. This is always written |
| capitalized. |
| |
| 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 |
| |