summaryrefslogtreecommitdiffstats
path: root/wiki/src/contribute/how/documentation/style_guide.mdwn
blob: 7151d0a141d4782398f0beeb9a5cbff4994d4e19 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
[[!meta title="Documentation style guide"]]

<a id="administration-password"></a>

- **administration password** vs **root password**

  Use *administration password*. Avoid *root password* even though many
  Linux users would use it.

  - *For example:*

    - [[Set up an administration password
      |doc/first_steps/startup_options/administration_password]] when
      you start Tails.

    - Start Tails and [[set up an administration
      password|doc/first_steps/startup_options/administration_password]].

<a id="anchors"></a>

- **anchors** (HTML anchors)

  Use HTML anchors to provide shortcuts when pointing people to sections
  inside a page.

  - *For example*:

    - `<a id="2014">` in `doc/about/finances` to be able to point to
      `https://tails.boum.org/finances#2014`.

  - Keep them as short as possible as they appear in the URL.

  - Use hyphens instead of underscores to separate words.

<a id="boot"></a>

- **boot** vs **start**

  - Use *start* and *restart* as much as possible to refer to starting a
    computer on Tails; *boot* is almost always unecessary jargon.

  - You might use *boot* when the word is displayed to the user by the
    computer or when writing for a technical audience, like in our
    design documentation.

  - Use *boot* when referring to *boot options*, which are only
    documented for workarounds or a technical audience.

  - *For example*:

    - Most computers do not start on Tails by default.

    - The following instructions explain how to display the boot menu
      and start on the USB stick.

    - When starting Tails, add the <span class="command">toram</span>
      boot option in the <span class="application">Boot Loader
      Menu</span>. For detailed instructions, see the documentation on
      [[using the <span class="application">Boot Loader
      Menu</span>|doc/first_steps/startup_options#boot_loader_menu]].

<a id="bulleted-lists"></a>

- **bulleted lists**

  Refer to this article from NN/g on [presenting bulleted
  lists](https://www.nngroup.com/articles/presenting-bulleted-lists/).

  Always add empty lines between list items to:

  - Make them easier to read.

  - Make them easier to translate. Each item from the list will be put
    in a separate PO string in PO files by the PO plugin when building
    the website.

<a id="debian-versions"></a>

- **Debian and Ubuntu versions**

  Refer to Debian and Ubuntu versions primarily by their numbers, and additionally
  by their codenames.

  - *For example*:

    - Tails 3.0 is based on Debian 9 (Stretch)

    - *Tails Installer* is available on Ubuntu 15.10 (Wily Werewolf) or later.

<a id="earlier"></a>

- **earlier** and **later**

  Use to refer to versions of software.

  Don't use *lower* and *higher* or *newer* and *older*.

  Don't use "regular expressions" like *Tails 2.1.&#42;*.

  - *For example:*

    - If you are running macOS 10.10 (Yosemite) or earlier

<a id="future-tense"></a>

- **future tense**

Whenever possible, use present, not future, tense. Don't switch
unnecessarily from present to future tense when present tense is
sufficient to express a sequence of steps or events.

Present tense is easier to read than past or future tense. Simple verbs
are easier to read and understand than complex verbs, such as verbs in
the progressive or perfect tense.

<a id="digit-grouping"></a>

- **digit grouping**

  Use a non-breaking thin space (HTML entity: `&#8239;`) or a space to separate
  groups of three digits.

  - *For example*:

    - $50&#8239;000

  See [[!wikipedia Decimal_separator#Digit_grouping]] and [[!wikipedia
  ISO_31-0#Numbers]].

<a id="gnome-application"></a>

- **GNOME applications: <i>Files</i>, <i>Disks</i>, etc.**

  GNOME applications that have a common noun as their name (like
  <span class="application">Files</span> or
  <span class="application">Disks</span>) can be confusing when referred
  to in the documentation.

  Make sure to clarify that you are referring to an application (and
  not, for example, a set of files or disks):

  - *For example*:

    - In the title of sections

    - When first referring to the application in a section

  - *Use*:

    - The <span class="application">Files</span> browser

    - The <span class="application">Disks</span> utility

  Otherwise, use the short name of the application as it appears in the menus when giving
  instructions to be executed inside Tails.

  - *For example*:

    - Open */live/persistence/TailsData_unlocked/dotfiles* in *Files*.

  Prepend "*GNOME*" when giving instructions to be executed outside of
  Tails.

  - *For example*:

    - Install <span class="application">GNOME Disks</span> in Debian.

<a id="graphics-card"></a>

- **graphics card**

  And not *graphics adapters*, *graphics*, *graphical hardware*, or
  *video card*.

<a id="media"></a>

- **media** and **installation media**

  Use only in rare occasions where it is especially relevant to mention
  both USB sticks and DVDs.

  Tails is now primarily advertised for USB sticks. We prefer making our
  text easy to read for the majority of people using USB sticks than to
  be exhaustive and always mention DVDs, implicitly or explicitly.

  - *For example*:

    - Tails runs on a USB stick that you can plug in and use on almost
      any computer.

    - It is not possible to install Tails on a hard disk. Tails is
      designed to be a live system running from a removable media: USB
      stick or DVD.

<a id="network-interface"></a>

- **network interface**, **Wi-Fi interface**

  And not *card*, *device*, or *adapter*.

  Still, **USB Wi-Fi adapters** are USB dongles that provide a Wi-Fi interface.

<a id="persistence-feature"></a>

- **persistence feature**

  To refer to the features available in the configuration of the
  *persistent storage*.

  - *For example*:

    - [&hellip;] when the [[<span class="guilabel">Additional Software</span>
      persistence feature|doc/first_steps/persistence/configure#additional_software]]
      is activated.

  The word *persistence* can be omitted if it is redundant from the context
  (for example on [[doc/first_steps/persistence/configure]]).

<a id="procedures"></a>

- **procedures** (a series of steps)

  - Keep the number of steps low within a procedure (for example, below
    10, ideally 7). For longer procedures, split them and give each
    section a title.

  - Add a blank line between each step.

  - Rely on the automatic numbered of Markdown and number all the steps
    with `1.`

  See also the *Microsoft Manual of Style: Procedures and technical
  content*.

  - *For example*:

<pre>
1. Make sure that you are connected to the Internet.

1. Start <span class="application">Software Sources</span>.

1. Click on the <span class="guilabel">PPAs</span> button and then choose to <span class="button">Add a new PPA&hellip;</span>.
</pre>

<a id="secure-boot"></a>

- **Secure Boot**

  Capitalize as a brand or feature. Writing *secure boot* would make it
  sound more like a magic security feature (which it is not).

<a id="serial-comma"></a>

- **serial comma**

  Place a [[!wikipedia serial comma]] immediately before the
  coordinating conjunction (usually *and* or *or*) in a series of three
  or more terms.

<a id="startup-options"></a>

- **startup options**

  To refer to the kernel command line options that can be specified from
  the *Boot Loader Menu*.

  - *For example:*

    - Adding `radeon.dpm=0` to the [[startup
      options|/doc/first_steps/startup_options#boot_menu]].

<a id="tails-greeter"></a>

- **<span class="application">Tails Greeter</span>**

  Without an article. Not *the Greeter*. Note the formatting as an application.

<a id="update"></a>

- **update** vs **upgrade**

  - Use **upgrade** to refer to the replacement of a previous version of
    Tails by another.

  - *For example:*

    - If you know someone you trust who already did the upgrade, you can
      upgrade your Tails by cloning from their Tails.</p>

  - You might use **update** to refer to other operations that update
    some data or software outside of Tails releases.

  - *For example:*

    - Make sure to update your *dotfiles* each time you use the **init**
      command of *keyringer*.

    - The packages from your list of additional software will be updated
      automatically when you connect to the Internet.

<a id="vulnerability"></a>

- **vulnerability** or **security vulnerability**

  And not *hole* or *issue*.