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

sajolida's avatar
sajolida committed
3
4
5
6
7
8
9
10
11
12
13
14
15
16
- **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
17
- **bulleted lists**
18
19
20
21

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

22
23
24
25
26
27
28
29
  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.

cbrownstein's avatar
cbrownstein committed
30
- **Debian and Ubuntu versions**
sajolida's avatar
sajolida committed
31

cbrownstein's avatar
cbrownstein committed
32
33
  Refer to Debian and Ubuntu versions primarily by their numbers, and additionally
  by their codenames.
sajolida's avatar
sajolida committed
34

sajolida's avatar
sajolida committed
35
36
  - *For example*:

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

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

sajolida's avatar
sajolida committed
41
42
<a id="digit_grouping"></a>

43
44
- **digit grouping**

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

sajolida's avatar
sajolida committed
48
49
  - *For example*:

sajolida's avatar
sajolida committed
50
    - $50&#8239;000
51
52
53

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

55
<a id="gnome_application"></a>
56

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

59
60
  GNOME applications that have a common noun as their name (like
  <span class="application">Files</span> or
cbrownstein's avatar
cbrownstein committed
61
  <span class="application">Disks</span>) can be confusing when referred
62
  to in the documentation.
63

64
  Make sure to clarify that you are referring to an application (and
cbrownstein's avatar
cbrownstein committed
65
  not, for example, a set of files or disks):
66
67

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

69
    - In the title of sections
sajolida's avatar
sajolida committed
70

71
72
73
    - When first referring to the application in a section

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

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

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

cbrownstein's avatar
cbrownstein committed
79
  Otherwise, use the short name of the application as it appears in the menus when giving
80
81
82
  instructions to be executed inside Tails.

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

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

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

89
  - *For example*:
sajolida's avatar
sajolida committed
90

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

sajolida's avatar
sajolida committed
93
94
- **graphics card**

95
96
  And not *graphics adapters*, *graphics*, *graphical hardware*, or
  *video card*.
sajolida's avatar
sajolida committed
97

sajolida's avatar
sajolida committed
98
99
100
101
102
103
104
105
106
107
108
109
110
111
- **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
112
  - *For example*:
sajolida's avatar
sajolida committed
113
114
115
116
117
118
119
120
121

<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
122
123
124
125
126
127
- **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.

128
129
130
- **persistence feature**

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

sajolida's avatar
sajolida committed
133
134
135
136
137
  - *For example*:

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

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

142
143
144
145
146
- **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).

147
148
149
150
151
152
- **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
153
154
155
156
157
- **startup options**

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

sajolida's avatar
sajolida committed
158
159
160
161
  - *For example:*

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

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

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

sajolida's avatar
sajolida committed
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
- **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
188
189
190
- **vulnerability** or **security vulnerability**

  And not *hole* or *issue*.