doc/core/development/policy/writing-standard.html

   1 <?xml version="1.0" encoding="utf-8"?><!DOCTYPE html  PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
   2   <head>
   3 <title>Twisted Documentation: Twisted Writing Standard</title>
   4 <link href="../../howto/stylesheet.css" rel="stylesheet" type="text/css"/>
   5   </head>
   6
   7   <body bgcolor="white">
   8     <h1 class="title">Twisted Writing Standard</h1>
   9     <div class="toc"><ol><li><a href="#auto0">General style</a></li><li><a href="#auto1">Evangelism and usage documents</a></li><li><a href="#auto2">Descriptions of features</a></li><li><a href="#auto3">Linking</a></li><li><a href="#auto4">Introductions</a></li><ul><li><a href="#auto5">Introductory paragraph</a></li><li><a href="#auto6">Description of target audience</a></li><li><a href="#auto7">Goals of document</a></li></ul><li><a href="#auto8">Example code</a></li><li><a href="#auto9">Conclusions</a></li></ol></div>
  10     <div class="content">
  11     <span/>
  12
  13     <p>The Twisted writing standard describes the documentation writing
  14     styles we prefer in our documentation. This standard applies particularly
  15     to howtos and other descriptive documentation.</p>
  16
  17     <p>This document should be read with the <a href="doc-standard.html" shape="rect">documentation standard</a>, which describes
  18     markup style for the documentation.</p>
  19
  20     <p>This document is meant to help Twisted documentation authors produce
  21     documentation that does not have the following problems:</p>
  22
  23     <ul>
  24     <li>misleads users about what is good Twisted style;</li>
  25     <li>misleads users into thinking that an advanced howto is an introduction
  26     to writing their first Twisted server; and</li>
  27     <li>misleads users about whether they fit the document's target audience:
  28     for example, that they are able to use enterprise without knowing how to
  29     write SQL queries.</li>
  30     </ul>
  31
  32     <h2>General style<a name="auto0"/></h2>
  33
  34     <p>Documents should aim to be clear and concise, allowing the API
  35     documentation and the example code to tell as much of the story as they
  36     can. Demonstrations and where necessary supported arguments should always
  37     preferred to simple statements (&quot;here is how you would simplify this
  38     code with Deferreds&quot; rather than &quot;Deferreds make code
  39     simpler&quot;).</p>
  40
  41     <p>Documents should be clearly delineated into sections and subsections.
  42     Each of these sections, like the overall document, should have a single
  43     clear purpose. This is most easily tested by trying to have meaningful
  44     headings: a section which is headed by &quot;More details&quot; or
  45     &quot;Advanced stuff&quot; is not purposeful enough. There should be
  46     fairly obvious ways to split a document. The two most common are task
  47     based sectioning and sectioning which follows module and class
  48     separations.</p>
  49
  50     <p>Documentation must use American English spelling, and where possible
  51     avoid any local variants of either vocabulary or grammar. Grammatically
  52     complex sentences should ideally be avoided: these make reading
  53     unnecessarily difficult, particularly for non-native speakers.</p>
  54
  55     <h2>Evangelism and usage documents<a name="auto1"/></h2>
  56
  57     <p>The Twisted documentation should maintain a reasonable distinction
  58     between &quot;evangelism&quot; documentation, which compares the Twisted
  59     design or Twisted best practice with other approaches and argues for the
  60     Twisted approach, and &quot;usage&quot; documentation, which describes the
  61     Twisted approach in detail without comparison to other possible
  62     approaches.</p>
  63
  64     <p>While both kinds of documentation are useful, they have different
  65     audiences. The first kind of document, evangelical documents, is useful to
  66     a reader who is researching and comparing approaches and seeking to
  67     understand the Twisted approach or Twisted functionality in order to
  68     decide whether it is useful to them. The second kind of document, usage
  69     documents, are useful to a reader who has decided to use Twisted and
  70     simply wants further information about available functions and
  71     architectures they can use to accomplish their goal.</p>
  72
  73     <p>Since they have distinct audiences, evangelism and detailed usage
  74     documentation belongs in separate files. There should be links between
  75     them in 'Further reading' or similar sections.</p>
  76
  77     <h2>Descriptions of features<a name="auto2"/></h2>
  78
  79     <p>Descriptions of any feature added since release 2.0 of Twisted core
  80     must have a note describing which release of which Twisted project they
  81     were added in at the first mention in each document. If they are not yet
  82     released, give them the number of the next minor release.</p>
  83
  84     <p>For example, a substantial change might have a version number added in
  85     the introduction:</p>
  86
  87     <blockquote>
  88     This document describes the Application infrastructure for deploying
  89     Twisted applications <em>(added in Twisted 1.3)</em>.
  90     </blockquote>
  91
  92     <p>The version does not need to be mentioned elsewhere in the document
  93     except for specific features which were added in subsequent releases,
  94     which might should be mentioned separately.</p>
  95
  96     <blockquote>
  97     The simplest way to create a <code>.tac</code> file, SuperTac <em>(added
  98     in Twisted Core 99.7)</em>...</blockquote>
  99
 100     <p>In the case where the usage of a feature has substantially changed, the
 101     number should be that of the release in which the current usage became
 102     available. For example:</p>
 103
 104     <blockquote> This document describes the Application infrastructure for
 105     deploying Twisted applications <em>(updated[/substantially updated] in Twisted
 106     2.7)</em>.  </blockquote>
 107
 108     <h2>Linking<a name="auto3"/></h2>
 109
 110     <p>The first occurrence of the name of any module, class or function should
 111     always link to the API documents. Subsequent mentions may or may not link
 112     at the author's discretion: discussions which are very closely bound to a
 113     particular API should probably link in the first mention in the given
 114     section.</p>
 115
 116     <p>Links between howtos are encouraged. Overview documents and tutorials
 117     should always link to reference documents and in depth documents. These
 118     documents should link among themselves wherever it's needed: if you're
 119     tempted to re-describe the functionality of another module, you should
 120     certainly link instead.</p>
 121
 122     <h2>Introductions<a name="auto4"/></h2>
 123
 124     <p>The introductory section of a Twisted howto should immediately follow
 125     the top-level heading and precede any subheadings.</p>
 126
 127     <p>The following items should be present in the introduction to Twisted
 128     howtos: the introductory paragraph and the description of the target
 129     audience.</p>
 130
 131     <h3>Introductory paragraph<a name="auto5"/></h3>
 132
 133     <p>The introductory paragraph of a document should summarize what the
 134     document is designed to present. It should use the both proper names for
 135     the Twisted technologies and simple non-Twisted descriptions of the
 136     technologies. For example, in this paragraph both the name of the technology
 137     (&quot;Conch&quot;) and a description (&quot;SSH server&quot;) are used:</p>
 138
 139     <blockquote>
 140     This document describes setting up a SSH server to serve data from the
 141     file system using Conch, the Twisted SSH implementation.
 142     </blockquote>
 143
 144     <p>The introductory paragraph should be relatively short, but should, like
 145     the above, somewhere define the document's objective: what the reader
 146     should be able to do using instructions in the document.</p>
 147
 148     <h3>Description of target audience<a name="auto6"/></h3>
 149
 150     <p>Subsequent paragraphs in the introduction should describe the target
 151     audience of the document: who would want to read it, and what they should
 152     know before they can expect to use your document. For example:</p>
 153
 154     <blockquote>
 155     <p>
 156     The target audience of this document is a Twisted user who has a set of
 157     filesystem like data objects that they would like to make available to
 158     authenticated users over SFTP.
 159     </p>
 160
 161     <p>
 162     Following the directions in this document will require that you are
 163     familiar with managing authentication via the Twisted Cred system.
 164     </p>
 165     </blockquote>
 166
 167     <p>Use your discretion about the extent to which you list assumed
 168     knowledge. Very introductory documents that are going to be among a
 169     reader's first exposure to Twisted will even need to specify that they
 170     rely on knowledge of Python and of certain networking concepts (ports,
 171     servers, clients, connections) but documents that are going to be sought
 172     out by existing Twisted users for particular purposes only need to specify
 173     other Twisted knowledge that is assumed.</p>
 174
 175     <p>Any knowledge of technologies that wouldn't be considered &quot;core
 176     Python&quot; and/or &quot;simple networking&quot; need to be explicitly
 177     specified, no matter how obvious they seem to someone familiar with the
 178     technology. For example, it needs to be stated that someone using
 179     enterprise should know SQL and should know how to set up and populate
 180     databases for testing purposes.</p>
 181
 182     <p>Where possible, link to other documents that will fill in missing
 183     knowledge for the reader. Linking to documents in the Twisted repository
 184     is preferred but not essential.</p>
 185
 186     <h3>Goals of document<a name="auto7"/></h3>
 187
 188     <p>The introduction should finish with a list of tasks that the user can
 189     expect to see the document accomplish. These tasks should be concrete
 190     rather than abstract, so rather than telling the user that they will
 191     &quot;understand Twisted Conch&quot;, you would list the specific tasks
 192     that they will see the document do. For example:</p>
 193
 194     <blockquote>
 195     <p>
 196     This document will demonstrate the following tasks using Twisted Conch:
 197     </p>
 198
 199     <ul>
 200     <li>creating an anonymous access read-only SFTP server using a filesystem
 201     backend;</li>
 202     <li>creating an anonymous access read-only SFTP server using a proxy
 203     backend connecting to an HTTP server; and</li>
 204     <li>creating a anonymous access read and write SFTP server using a
 205     filesystem backend.</li>
 206     </ul>
 207     </blockquote>
 208
 209     <p>In many cases this will essentially be a list of your code examples,
 210     but it need not be. If large sections of your code are devoted to design
 211     discussions, your goals might resemble the following:</p>
 212
 213     <blockquote>
 214     <p>
 215     This document will discuss the following design aspects of writing Conch
 216     servers:
 217     </p>
 218
 219     <ul>
 220     <li>authentication of users; and</li>
 221     <li>choice of data backends.</li>
 222     </ul>
 223     </blockquote>
 224
 225
 226     <h2>Example code<a name="auto8"/></h2>
 227
 228     <p>Wherever possible, example code should be provided to illustrate a
 229     certain technique or piece of functionality.</p>
 230
 231     <p>Example code should try and meet as many of the following requirements
 232     as possible:</p>
 233
 234     <ul>
 235     <li>example code should be a complete working example suitable for copying
 236     and pasting and running by the reader (where possible, provide a link to a
 237     file to download);</li>
 238     <li>example code should be short;</li>
 239     <li>example code should be commented very extensively, with the assumption
 240     that this code may be read by a Twisted newcomer;</li>
 241     <li>example code should conform to the <a href="coding-standard.html" shape="rect">coding standard</a>; and</li>
 242     <li>example code should exhibit 'best practice', not only for dealing with
 243     the target functionality, but also for use of the application framework
 244     and so on.</li>
 245     </ul>
 246
 247     <p>The requirement to have a complete working example will occasionally
 248     impose upon authors the need to have a few dummy functions: in Twisted
 249     documentation the most common example is where a function is needed to
 250     generate a Deferred and fire it after some time has passed. An example
 251     might be this, where <code class="API"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.internet.task.deferLater.html" title="twisted.internet.task.deferLater">deferLater</a></code> is used to fire a callback
 252     after a period of time:</p>
 253
 254     <pre class="python"><p class="py-linenumber">1
 255 2
 256 3
 257 4
 258 5
 259 6
 260 7
 261 8
 262 </p><span class="py-src-keyword">from</span> <span class="py-src-variable">twisted</span>.<span class="py-src-variable">internet</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">task</span>, <span class="py-src-variable">reactor</span>
 263
 264     <span class="py-src-keyword">def</span> <span class="py-src-identifier">getDummyDeferred</span>():
 265         <span class="py-src-string">&quot;&quot;&quot;
 266         Dummy method which returns a deferred that will fire in 5 seconds with
 267         a result
 268         &quot;&quot;&quot;</span>
 269         <span class="py-src-keyword">return</span> <span class="py-src-variable">task</span>.<span class="py-src-variable">deferLater</span>(<span class="py-src-variable">reactor</span>, <span class="py-src-number">5</span>, <span class="py-src-keyword">lambda</span> <span class="py-src-variable">x</span>: <span class="py-src-string">&quot;RESULT&quot;</span>)
 270 </pre>
 271
 272     <p>As in the above example, it is imperative to clearly mark that the
 273     function is a dummy in as many ways as you can: using <code>Dummy</code> in
 274     the function name, explaining that it is a dummy in the docstring, and
 275     marking particular lines as being required to create an effect for the
 276     purposes of demonstration. In most cases, this will save the reader from
 277     mistaking this dummy method for an idiom they should use in their Twisted
 278     code.</p>
 279
 280     <h2>Conclusions<a name="auto9"/></h2>
 281
 282     <p>The conclusion of a howto should follow the very last section heading
 283     in a file. This heading would usually be called &quot;Conclusion&quot;.</p>
 284
 285     <p>The conclusion of a howto should remind the reader of the tasks that
 286     they have done while reading the document. For example:</p>
 287
 288     <blockquote>
 289     <p>
 290     In this document, you have seen how to:
 291     </p>
 292
 293     <ol>
 294     <li>set up an anonymous read-only SFTP server;</li>
 295     <li>set up a SFTP server where users authenticate;</li>
 296     <li>set up a SFTP server where users are restricted to some parts of the
 297     filesystem based on authentication; and</li>
 298     <li>set up a SFTP server where users have write access to some parts of
 299     the filesystem based on authentication.</li>
 300     </ol>
 301     </blockquote>
 302
 303     <p>If appropriate, the howto could follow this description with links to
 304     other documents that might be of interest to the reader with their
 305     newfound knowledge. However, these links should be limited to fairly
 306     obvious extensions of at least one of the listed tasks.</p>
 307
 308   </div>
 309
 310     <p><a href="../../howto/index.html">Index</a></p>
 311     <span class="version">Version: 12.1.0</span>
 312   </body>
 313 </html>