style_guide.mdwn 8.54 KB
Newer Older
1 2
[[!meta title="Documentation style guide"]]

sajolida's avatar
sajolida committed
3 4
<a id="administration-password"></a>

5 6 7 8 9 10 11 12 13 14 15 16 17 18
- **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]].

sajolida's avatar
sajolida committed
19 20
<a id="anchors"></a>

sajolida's avatar
sajolida committed
21 22 23 24 25 26 27 28 29 30 31 32 33 34
- **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.

sajolida's avatar
sajolida committed
35 36
<a id="boot"></a>

sajolida's avatar
sajolida committed
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
- **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]].

sajolida's avatar
sajolida committed
62 63
<a id="bulleted-lists"></a>

sajolida's avatar
sajolida committed
64
- **bulleted lists**
65 66 67 68

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

69 70 71 72 73 74 75 76
  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.

sajolida's avatar
sajolida committed
77 78
<a id="debian-versions"></a>

cbrownstein's avatar
cbrownstein committed
79
- **Debian and Ubuntu versions**
sajolida's avatar
sajolida committed
80

cbrownstein's avatar
cbrownstein committed
81 82
  Refer to Debian and Ubuntu versions primarily by their numbers, and additionally
  by their codenames.
sajolida's avatar
sajolida committed
83

sajolida's avatar
sajolida committed
84 85
  - *For example*:

sajolida's avatar
sajolida committed
86
    - Tails 3.0 is based on Debian 9 (Stretch)
sajolida's avatar
sajolida committed
87

sajolida's avatar
sajolida committed
88
    - *Tails Installer* is available on Ubuntu 15.10 (Wily Werewolf) or later.
89

sajolida's avatar
sajolida committed
90 91
<a id="earlier"></a>

sajolida's avatar
sajolida committed
92 93 94 95 96 97 98 99 100 101 102 103
- **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

sajolida's avatar
sajolida committed
104 105
<a id="future-tense"></a>

sajolida's avatar
sajolida committed
106 107 108 109 110 111 112 113 114 115
- **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.

sajolida's avatar
sajolida committed
116
<a id="digit-grouping"></a>
sajolida's avatar
sajolida committed
117

118 119
- **digit grouping**

sajolida's avatar
sajolida committed
120
  Use a non-breaking thin space (HTML entity: `&#8239;`) or a space to separate
121 122
  groups of three digits.

sajolida's avatar
sajolida committed
123 124
  - *For example*:

sajolida's avatar
sajolida committed
125
    - $50&#8239;000
126 127 128

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

sajolida's avatar
sajolida committed
130
<a id="gnome-application"></a>
131

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

134 135
  GNOME applications that have a common noun as their name (like
  <span class="application">Files</span> or
cbrownstein's avatar
cbrownstein committed
136
  <span class="application">Disks</span>) can be confusing when referred
137
  to in the documentation.
138

139
  Make sure to clarify that you are referring to an application (and
cbrownstein's avatar
cbrownstein committed
140
  not, for example, a set of files or disks):
141 142

  - *For example*:
sajolida's avatar
sajolida committed
143

144
    - In the title of sections
sajolida's avatar
sajolida committed
145

146 147 148
    - When first referring to the application in a section

  - *Use*:
sajolida's avatar
sajolida committed
149

150
    - The <span class="application">Files</span> browser
sajolida's avatar
sajolida committed
151

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

cbrownstein's avatar
cbrownstein committed
154
  Otherwise, use the short name of the application as it appears in the menus when giving
155 156 157
  instructions to be executed inside Tails.

  - *For example*:
sajolida's avatar
sajolida committed
158

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

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

164
  - *For example*:
sajolida's avatar
sajolida committed
165

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

sajolida's avatar
sajolida committed
168 169
<a id="graphics-card"></a>

sajolida's avatar
sajolida committed
170 171
- **graphics card**

172 173
  And not *graphics adapters*, *graphics*, *graphical hardware*, or
  *video card*.
sajolida's avatar
sajolida committed
174

sajolida's avatar
sajolida committed
175 176 177 178 179 180
<a id="internet"></a>

- **Internet**

  Capitalize. When used as a noun, always preceded by *the*.

sajolida's avatar
sajolida committed
181 182
<a id="media"></a>

sajolida's avatar
sajolida committed
183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200
- **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.

sajolida's avatar
sajolida committed
201 202
<a id="network-interface"></a>

sajolida's avatar
sajolida committed
203 204 205 206 207 208
- **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.

sajolida's avatar
sajolida committed
209 210
<a id="persistence-feature"></a>

sajolida's avatar
sajolida committed
211 212 213 214 215 216 217 218 219 220 221 222 223 224
- **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]]).

sajolida's avatar
sajolida committed
225 226 227 228 229 230 231
<a id="please"></a>

- **please**

  Avoid please except in situations where the user is asked to do
  something inconvenient or the software is to blame for the situation.

sajolida's avatar
sajolida committed
232 233
<a id="procedures"></a>

sajolida's avatar
sajolida committed
234 235 236 237 238 239 240 241 242 243 244 245 246 247
- **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*.

sajolida's avatar
sajolida committed
248
  - *For example*:
sajolida's avatar
sajolida committed
249 250 251 252 253 254 255 256 257

<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>

sajolida's avatar
sajolida committed
258 259
<a id="secure-boot"></a>

260 261 262 263 264
- **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).

sajolida's avatar
sajolida committed
265 266
<a id="serial-comma"></a>

267 268 269 270 271 272
- **serial comma**

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

sajolida's avatar
sajolida committed
273 274
<a id="startup-options"></a>

sajolida's avatar
sajolida committed
275 276 277 278 279
- **startup options**

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

sajolida's avatar
sajolida committed
280 281 282 283
  - *For example:*

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

sajolida's avatar
sajolida committed
285 286
<a id="tails-greeter"></a>

sajolida's avatar
sajolida committed
287
- **<span class="application">Tails Greeter</span>**
288

sajolida's avatar
sajolida committed
289
  Without an article. Not *the Greeter*. Note the formatting as an application.
sajolida's avatar
sajolida committed
290

sajolida's avatar
sajolida committed
291 292
<a id="update"></a>

sajolida's avatar
sajolida committed
293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313
- **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.

sajolida's avatar
sajolida committed
314 315
<a id="vulnerability"></a>

sajolida's avatar
sajolida committed
316 317 318
- **vulnerability** or **security vulnerability**

  And not *hole* or *issue*.