Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | .. highlightlang:: rest |
| 2 | |
Alexander Belopolsky | ea3e91e | 2010-11-11 22:43:45 +0000 | [diff] [blame] | 3 | Style guide |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 4 | =========== |
| 5 | |
| 6 | The Python documentation should follow the `Apple Publications Style Guide`_ |
| 7 | wherever possible. This particular style guide was selected mostly because it |
| 8 | seems reasonable and is easy to get online. |
| 9 | |
Alexander Belopolsky | ea3e91e | 2010-11-11 22:43:45 +0000 | [diff] [blame] | 10 | Topics which are either not covered in Apple's style guide or treated |
| 11 | differently in Python documentation will be discussed in this |
| 12 | document. |
| 13 | |
| 14 | Use of whitespace |
| 15 | ----------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | |
| 17 | All reST files use an indentation of 3 spaces. The maximum line length is 80 |
| 18 | characters for normal text, but tables, deeply indented code samples and long |
| 19 | links may extend beyond that. |
| 20 | |
| 21 | Make generous use of blank lines where applicable; they help grouping things |
| 22 | together. |
| 23 | |
| 24 | A sentence-ending period may be followed by one or two spaces; while reST |
| 25 | ignores the second space, it is customarily put in by some users, for example |
| 26 | to aid Emacs' auto-fill mode. |
| 27 | |
Alexander Belopolsky | ea3e91e | 2010-11-11 22:43:45 +0000 | [diff] [blame] | 28 | Footnotes |
| 29 | --------- |
| 30 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | Footnotes are generally discouraged, though they may be used when they are the |
| 32 | best way to present specific information. When a footnote reference is added at |
| 33 | the end of the sentence, it should follow the sentence-ending punctuation. The |
| 34 | reST markup should appear something like this:: |
| 35 | |
| 36 | This sentence has a footnote reference. [#]_ This is the next sentence. |
| 37 | |
| 38 | Footnotes should be gathered at the end of a file, or if the file is very long, |
| 39 | at the end of a section. The docutils will automatically create backlinks to |
| 40 | the footnote reference. |
| 41 | |
| 42 | Footnotes may appear in the middle of sentences where appropriate. |
| 43 | |
Alexander Belopolsky | ea3e91e | 2010-11-11 22:43:45 +0000 | [diff] [blame] | 44 | Capitalization |
| 45 | -------------- |
| 46 | |
| 47 | .. sidebar:: Sentence case |
| 48 | |
| 49 | Sentence case is a set of capitalization rules used in English |
| 50 | sentences: the first word is always capitalized and other words are |
| 51 | only capitalized if there is a specific rule requiring it. |
| 52 | |
| 53 | Apple style guide recommends the use of title case in section titles. |
| 54 | However, rules for which words should be capitalized in title case |
| 55 | vary greaty between publications. |
| 56 | |
| 57 | In Python documentation, use of sentence case in section titles is |
| 58 | preferable, but consistency within a unit is more important than |
| 59 | following this rule. If you add a section to the chapter where most |
| 60 | sections are in title case you can either convert all titles to |
| 61 | sentence case or use the dominant style in the new section title. |
| 62 | |
| 63 | Sentences that start with a word for which specific rules require |
| 64 | starting it with a lower case letter should be avoided in titles and |
| 65 | elsewhere. |
| 66 | |
| 67 | .. note:: |
| 68 | |
| 69 | Sections that describe a library module often have titles in the |
| 70 | form of "modulename --- Short description of the module." In this |
| 71 | case, the description should be capitalized as a stand-alone |
| 72 | sentence. |
| 73 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | Many special names are used in the Python documentation, including the names of |
| 75 | operating systems, programming languages, standards bodies, and the like. Most |
| 76 | of these entities are not assigned any special markup, but the preferred |
| 77 | spellings are given here to aid authors in maintaining the consistency of |
| 78 | presentation in the Python documentation. |
| 79 | |
| 80 | Other terms and words deserve special mention as well; these conventions should |
| 81 | be used to ensure consistency throughout the documentation: |
| 82 | |
| 83 | CPU |
Alexander Belopolsky | ea3e91e | 2010-11-11 22:43:45 +0000 | [diff] [blame] | 84 | For "central processing unit." Many style guides say this should be |
| 85 | spelled out on the first use (and if you must use it, do so!). For |
| 86 | the Python documentation, this abbreviation should be avoided since |
| 87 | there's no reasonable way to predict which occurrence will be the |
| 88 | first seen by the reader. It is better to use the word "processor" |
| 89 | instead. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
| 91 | POSIX |
Alexander Belopolsky | ea3e91e | 2010-11-11 22:43:45 +0000 | [diff] [blame] | 92 | The name assigned to a particular group of standards. This is always |
| 93 | uppercase. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 94 | |
| 95 | Python |
Alexander Belopolsky | ea3e91e | 2010-11-11 22:43:45 +0000 | [diff] [blame] | 96 | The name of our favorite programming language is always capitalized. |
| 97 | |
| 98 | reST |
| 99 | For "reStructuredText," an easy to read, plaintext markup syntax |
| 100 | used to produce Python documentation. When spelled out, it is |
| 101 | always one word and both forms start with a lower case 'r'. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | |
| 103 | Unicode |
Alexander Belopolsky | ea3e91e | 2010-11-11 22:43:45 +0000 | [diff] [blame] | 104 | The name of a character coding system. This is always written |
| 105 | capitalized. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | |
| 107 | Unix |
Alexander Belopolsky | ea3e91e | 2010-11-11 22:43:45 +0000 | [diff] [blame] | 108 | The name of the operating system developed at AT&T Bell Labs in the early |
| 109 | 1970s. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 110 | |
Raymond Hettinger | bb1cf8d | 2011-05-10 00:35:03 -0700 | [diff] [blame] | 111 | Affirmative Tone |
| 112 | ---------------- |
| 113 | |
| 114 | The documentation focuses on affirmatively stating what the language does and |
| 115 | how to use it effectively. |
| 116 | |
| 117 | Except for certain security risks or segfault risks, the docs should avoid |
| 118 | wording along the lines of "feature x is dangerous" or "experts only". These |
| 119 | kinds of value judgments belong in external blogs and wikis, not in the core |
| 120 | documentation. |
| 121 | |
| 122 | Bad example (creating worry in the mind of a reader): |
| 123 | |
| 124 | Warning: failing to explicitly close a file could result in lost data or |
| 125 | excessive resource consumption. Never rely on reference counting to |
| 126 | automatically close a file. |
| 127 | |
| 128 | Good example (establishing confident knowledge in the effective use of the language): |
| 129 | |
| 130 | A best practice for using files is use a try/finally pair to explicitly |
| 131 | close a file after it is used. Alternatively, using a with-statement can |
| 132 | achieve the same effect. This assures that files are flushed and file |
| 133 | descriptor resources are released in a timely manner. |
| 134 | |
| 135 | Economy of Expression |
| 136 | --------------------- |
| 137 | |
Éric Araujo | d4701f4 | 2011-05-25 18:13:29 +0200 | [diff] [blame^] | 138 | More documentation is not necessarily better documentation. Err on the side |
Raymond Hettinger | bb1cf8d | 2011-05-10 00:35:03 -0700 | [diff] [blame] | 139 | of being succinct. |
| 140 | |
| 141 | It is an unfortunate fact that making documentation longer can be an impediment |
| 142 | to understanding and can result in even more ways to misread or misinterpret the |
| 143 | text. Long descriptions full of corner cases and caveats can create the |
| 144 | impression that a function is more complex or harder to use than it actually is. |
| 145 | |
| 146 | The documentation for :func:`super` is an example of where a good deal of |
| 147 | information was condensed into a few short paragraphs. Discussion of |
| 148 | :func:`super` could have filled a chapter in a book, but it is often easier to |
| 149 | grasp a terse description than a lengthy narrative. |
| 150 | |
| 151 | |
| 152 | Code Examples |
| 153 | ------------- |
| 154 | |
| 155 | Short code examples can be a useful adjunct to understanding. Readers can often |
| 156 | grasp a simple example more quickly than they can digest a formal description in |
| 157 | prose. |
| 158 | |
| 159 | People learn faster with concrete, motivating examples that match the context of |
| 160 | a typical use case. For instance, the :func:`str.rpartition` method is better |
| 161 | demonstrated with an example splitting the domain from a URL than it would be |
| 162 | with an example of removing the last word from a line of Monty Python dialog. |
| 163 | |
| 164 | The ellipsis for the :attr:`sys.ps2` secondary interpreter prompt should only be |
| 165 | used sparingly, where it is necessary to clearly differentiate between input |
| 166 | lines and output lines. Besides contributing visual clutter, it makes it |
| 167 | difficult for readers to cut-and-paste examples so they can experiment with |
| 168 | variations. |
| 169 | |
| 170 | Code Equivalents |
| 171 | ---------------- |
| 172 | |
| 173 | Giving pure Python code equivalents (or approximate equivalents) can be a useful |
| 174 | adjunct to a prose description. A documenter should carefully weigh whether the |
| 175 | code equivalent adds value. |
| 176 | |
| 177 | A good example is the code equivalent for :func:`all`. The short 4-line code |
| 178 | equivalent is easily digested; it re-emphasizes the early-out behavior; and it |
| 179 | clarifies the handling of the corner-case where the iterable is empty. In |
| 180 | addition, it serves as a model for people wanting to implement a commonly |
| 181 | requested alternative where :func:`all` would return the specific object |
| 182 | evaluating to False whenever the function terminates early. |
| 183 | |
| 184 | A more questionable example is the code for :func:`itertools.groupby`. Its code |
| 185 | equivalent borders on being too complex to be a quick aid to understanding. |
| 186 | Despite its complexity, the code equivalent was kept because it serves as a |
| 187 | model to alternative implementations and because the operation of the "grouper" |
| 188 | is more easily shown in code than in English prose. |
| 189 | |
| 190 | An example of when not to use a code equivalent is for the :func:`oct` function. |
| 191 | The exact steps in converting a number to octal doesn't add value for a user |
| 192 | trying to learn what the function does. |
| 193 | |
| 194 | Audience |
| 195 | -------- |
| 196 | |
| 197 | The tone of the tutorial (and all the docs) needs to be respectful of the |
| 198 | reader's intelligence. Don't presume that the readers are stupid. Lay out the |
| 199 | relevant information, show motivating use cases, provide glossary links, and do |
Éric Araujo | d4701f4 | 2011-05-25 18:13:29 +0200 | [diff] [blame^] | 200 | your best to connect-the-dots, but don't talk down to them or waste their time. |
Raymond Hettinger | bb1cf8d | 2011-05-10 00:35:03 -0700 | [diff] [blame] | 201 | |
| 202 | The tutorial is meant for newcomers, many of whom will be using the tutorial to |
| 203 | evaluate the language as a whole. The experience needs to be positive and not |
| 204 | leave the reader with worries that something bad will happen if they make a |
| 205 | misstep. The tutorial serves as guide for intelligent and curious readers, |
| 206 | saving details for the how-to guides and other sources. |
| 207 | |
| 208 | Be careful accepting requests for documentation changes from the rare but vocal |
| 209 | category of reader who is looking for vindication for one of their programming |
| 210 | errors ("I made a mistake, therefore the docs must be wrong ..."). Typically, |
| 211 | the documentation wasn't consulted until after the error was made. It is |
| 212 | unfortunate, but typically no documentation edit would have saved the user from |
| 213 | making false assumptions about the language ("I was surprised by ..."). |
| 214 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 215 | |
Georg Brandl | 386bc6d | 2010-04-25 10:19:53 +0000 | [diff] [blame] | 216 | .. _Apple Publications Style Guide: http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 217 | |