1
<?xml version="1.0"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: Twisted Writing Standard</title><link href="../../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Twisted Writing Standard</h1><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><div class="content"><span></span><p>The Twisted writing standard describes the documentation writing
3
styles we prefer in our documentation. This standard applies particularly
4
to howtos and other descriptive documentation.</p><p>This document should be read with the <a href="doc-standard.html">documentation standard</a>, which describes
5
markup style for the documentation.</p><p>This document is meant to help Twisted documentation authors produce
6
documentation that does not have the following problems:</p><ul><li>misleads users about what is good Twisted style;</li><li>misleads users into thinking that an advanced howto is an introduction
7
to writing their first Twisted server; and</li><li>misleads users about whether they fit the document's target audience:
8
for example, that they are able to use enterprise without knowing how to
9
write SQL queries.</li></ul><h2>General style<a name="auto0"></a></h2><p>Documents should aim to be clear and concise, allowing the API
10
documentation and the example code to tell as much of the story as they
11
can. Demonstrations and where necessary supported arguments should always
12
preferred to simple statements ("here is how you would simplify this
13
code with Deferreds" rather than "Deferreds make code
14
simpler").</p><p>Documents should be clearly delineated into sections and subsections.
15
Each of these sections, like the overall document, should have a single
16
clear purpose. This is most easily tested by trying to have meaningful
17
headings: a section which is headed by "More details" or
18
"Advanced stuff" is not purposeful enough. There should be
19
fairly obvious ways to split a document. The two most common are task
20
based sectioning and sectioning which follows module and class
21
separations.</p><p>Documentation must use American English spelling, and where possible
22
avoid any local variants of either vocabulary or grammar. Grammatically
23
complex sentences should ideally be avoided: these make reading
24
unnecessarily difficult, particularly for non-native speakers.</p><h2>Evangelism and usage documents<a name="auto1"></a></h2><p>The Twisted documentation should maintain a reasonable distinction
25
between "evangelism" documentation, which compares the Twisted
26
design or Twisted best practice with other approaches and argues for the
27
Twisted approach, and "usage" documentation, which describes the
28
Twisted approach in detail without comparison to other possible
29
approaches.</p><p>While both kinds of documentation are useful, they have different
30
audiences. The first kind of document, evangelical documents, is useful to
31
a reader who is researching and comparing approaches and seeking to
32
understand the Twisted approach or Twisted functionality in order to
33
decide whether it is useful to them. The second kind of document, usage
34
documents, are useful to a reader who has decided to use Twisted and
35
simply wants further information about available functions and
36
architectures they can use to accomplish their goal.</p><p>Since they have distinct audiences, evangelism and detailed usage
37
documentation belongs in separate files. There should be links between
38
them in 'Further reading' or similar sections.</p><h2>Descriptions of features<a name="auto2"></a></h2><p>Descriptions of any feature added since release 2.0 of Twisted core
39
must have a note describing which release of which Twisted project they
40
were added in at the first mention in each document. If they are not yet
41
released, give them the number of the next minor release.</p><p>For example, a substantial change might have a version number added in
42
the introduction:</p><blockquote>
43
This document describes the Application infrastructure for deploying
44
Twisted applications <em>(added in Twisted 1.3)</em>.
45
</blockquote><p>The version does not need to be mentioned elsewhere in the document
46
except for specific features which were added in subsequent releases,
47
which might should be mentioned separately.</p><blockquote>
48
The simplest way to create a <code>.tac</code> file, SuperTac <em>(added
49
in Twisted Core 99.7)</em>...</blockquote><p>In the case where the usage of a feature has substantially changed, the
50
number should be that of the release in which the current usage became
51
available. For example:</p><blockquote> This document describes the Application infrastructure for
52
deploying Twisted applications <em>(updated[/substantially updated] in Twisted
53
2.7)</em>. </blockquote><h2>Linking<a name="auto3"></a></h2><p>The first occurrence of the name of any module, class or function should
54
always link to the API documents. Subsequent mentions may or may not link
55
at the author's discretion: discussions which are very closely bound to a
56
particular API should probably link in the first mention in the given
57
section.</p><p>Links between howtos are encouraged. Overview documents and tutorials
58
should always link to reference documents and in depth documents. These
59
documents should link among themselves wherever it's needed: if you're
60
tempted to re-describe the functionality of another module, you should
61
certainly link instead.</p><h2>Introductions<a name="auto4"></a></h2><p>The introductory section of a Twisted howto should immediately follow
62
the top-level heading and precede any subheadings.</p><p>The following items should be present in the introduction to Twisted
63
howtos: the introductory paragraph and the description of the target
64
audience.</p><h3>Introductory paragraph<a name="auto5"></a></h3><p>The introductory paragraph of a document should summarize what the
65
document is designed to present. It should use the both proper names for
66
the Twisted technologies and simple non-Twisted descriptions of the
67
technologies. For example, in this paragraph both the name of the technology
68
("Conch") and a description ("SSH server") are used:</p><blockquote>
69
This document describes setting up a SSH server to serve data from the
70
file system using Conch, the Twisted SSH implementation.
71
</blockquote><p>The introductory paragraph should be relatively short, but should, like
72
the above, somewhere define the document's objective: what the reader
73
should be able to do using instructions in the document.</p><h3>Description of target audience<a name="auto6"></a></h3><p>Subsequent paragraphs in the introduction should describe the target
74
audience of the document: who would want to read it, and what they should
75
know before they can expect to use your document. For example:</p><blockquote><p>
76
The target audience of this document is a Twisted user who has a set of
77
filesystem like data objects that they would like to make available to
78
authenticated users over SFTP.
80
Following the directions in this document will require that you are
81
familiar with managing authentication via the Twisted Cred system.
82
</p></blockquote><p>Use your discretion about the extent to which you list assumed
83
knowledge. Very introductory documents that are going to be among a
84
reader's first exposure to Twisted will even need to specify that they
85
rely on knowledge of Python and of certain networking concepts (ports,
86
servers, clients, connections) but documents that are going to be sought
87
out by existing Twisted users for particular purposes only need to specify
88
other Twisted knowledge that is assumed.</p><p>Any knowledge of technologies that wouldn't be considered "core
89
Python" and/or "simple networking" need to be explicitly
90
specified, no matter how obvious they seem to someone familiar with the
91
technology. For example, it needs to be stated that someone using
92
enterprise should know SQL and should know how to set up and populate
93
databases for testing purposes.</p><p>Where possible, link to other documents that will fill in missing
94
knowledge for the reader. Linking to documents in the Twisted repository
95
is preferred but not essential.</p><h3>Goals of document<a name="auto7"></a></h3><p>The introduction should finish with a list of tasks that the user can
96
expect to see the document accomplish. These tasks should be concrete
97
rather than abstract, so rather than telling the user that they will
98
"understand Twisted Conch", you would list the specific tasks
99
that they will see the document do. For example:</p><blockquote><p>
100
This document will demonstrate the following tasks using Twisted Conch:
101
</p><ul><li>creating an anonymous access read-only SFTP server using a filesystem
102
backend;</li><li>creating an anonymous access read-only SFTP server using a proxy
103
backend connecting to an HTTP server; and</li><li>creating a anonymous access read and write SFTP server using a
104
filesystem backend.</li></ul></blockquote><p>In many cases this will essentially be a list of your code examples,
105
but it need not be. If large sections of your code are devoted to design
106
discussions, your goals might resemble the following:</p><blockquote><p>
107
This document will discuss the following design aspects of writing Conch
109
</p><ul><li>authentication of users; and</li><li>choice of data backends.</li></ul></blockquote><h2>Example code<a name="auto8"></a></h2><p>Wherever possible, example code should be provided to illustrate a
110
certain technique or piece of functionality.</p><p>Example code should try and meet as many of the following requirements
111
as possible:</p><ul><li>example code should be a complete working example suitable for copying
112
and pasting and running by the reader (where possible, provide a link to a
113
file to download);</li><li>example code should be short;</li><li>example code should be commented very extensively, with the assumption
114
that this code may be read by a Twisted newcomer;</li><li>example code should conform to the <a href="coding-standard.html">coding standard</a>; and</li><li>example code should exhibit 'best practice', not only for dealing with
115
the target functionality, but also for use of the application framework
116
and so on.</li></ul><p>The requirement to have a complete working example will occasionally
117
impose upon authors the need to have a few dummy functions: in Twisted
118
documentation the most common example is where a function is needed to
119
generate a Deferred and fire it after some time has passed. An example
120
might be this, where <code base="twisted.internet.reactor" class="API">callLater</code> is used to simulate the
121
delayed firing of a Deferred:</p><pre class="python">
122
<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">defer</span>, <span class="py-src-variable">reactor</span>
124
<span class="py-src-keyword">def</span> <span class="py-src-identifier">getDummyDeferred</span>():
125
<span class="py-src-string">"""
126
Dummy method which generates a Deferred and simulates it being fired
128
"""</span>
129
<span class="py-src-variable">deferred</span> = <span class="py-src-variable">defer</span>.<span class="py-src-variable">Deferred</span>()
130
<span class="py-src-comment"># simulate the deferred firing 5 seconds from now using callLater
131
</span> <span class="py-src-variable">reactor</span>.<span class="py-src-variable">callLater</span>(<span class="py-src-number">5</span>, <span class="py-src-variable">deferred</span>.<span class="py-src-variable">callback</span>, <span class="py-src-string">"RESULT"</span>)
132
<span class="py-src-keyword">return</span> <span class="py-src-variable">deferred</span>
133
</pre><p>As in the above example, it is imperative to clearly mark that the
134
function is a dummy in as many ways as you can: using <code>Dummy</code> in
135
the function name, explaining that it is a dummy in the docstring, and
136
marking particular lines as being required to create an effect for the
137
purposes of demonstration. In most cases, this will save the reader from
138
mistaking this dummy method for an idiom they should use in their Twisted
139
code.</p><h2>Conclusions<a name="auto9"></a></h2><p>The conclusion of a howto should follow the very last section heading
140
in a file. This heading would usually be called "Conclusion".</p><p>The conclusion of a howto should remind the reader of the tasks that
141
they have done while reading the document. For example:</p><blockquote><p>
142
In this document, you have seen how to:
143
</p><ol><li>set up an anonymous read-only SFTP server;</li><li>set up a SFTP server where users authenticate;</li><li>set up a SFTP server where users are restricted to some parts of the
144
filesystem based on authentication; and</li><li>set up a SFTP server where users have write access to some parts of
145
the filesystem based on authentication.</li></ol></blockquote><p>If appropriate, the howto could follow this description with links to
146
other documents that might be of interest to the reader with their
147
newfound knowledge. However, these links should be limited to fairly
148
obvious extensions of at least one of the listed tasks.</p></div><p><a href="../../howto/index.html">Index</a></p><span class="version">Version: 2.4.0</span></body></html>
b'\\ No newline at end of file'
added
removed
doc/howto/policy/writing-standard.html
