style_guide.mdwn 6.13 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 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
- **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
42
- **bulleted lists**
43 44 45 46

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

47 48 49 50 51 52 53 54
  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
55
- **Debian and Ubuntu versions**
sajolida's avatar
sajolida committed
56

cbrownstein's avatar
cbrownstein committed
57 58
  Refer to Debian and Ubuntu versions primarily by their numbers, and additionally
  by their codenames.
sajolida's avatar
sajolida committed
59

sajolida's avatar
sajolida committed
60 61
  - *For example*:

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

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

sajolida's avatar
sajolida committed
66 67
<a id="digit_grouping"></a>

68 69
- **digit grouping**

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

sajolida's avatar
sajolida committed
73 74
  - *For example*:

sajolida's avatar
sajolida committed
75
    - $50&#8239;000
76 77 78

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

80
<a id="gnome_application"></a>
81

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

84 85
  GNOME applications that have a common noun as their name (like
  <span class="application">Files</span> or
cbrownstein's avatar
cbrownstein committed
86
  <span class="application">Disks</span>) can be confusing when referred
87
  to in the documentation.
88

89
  Make sure to clarify that you are referring to an application (and
cbrownstein's avatar
cbrownstein committed
90
  not, for example, a set of files or disks):
91 92

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

94
    - In the title of sections
sajolida's avatar
sajolida committed
95

96 97 98
    - When first referring to the application in a section

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

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

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

cbrownstein's avatar
cbrownstein committed
104
  Otherwise, use the short name of the application as it appears in the menus when giving
105 106 107
  instructions to be executed inside Tails.

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

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

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

114
  - *For example*:
sajolida's avatar
sajolida committed
115

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

sajolida's avatar
sajolida committed
118 119
- **graphics card**

120 121
  And not *graphics adapters*, *graphics*, *graphical hardware*, or
  *video card*.
sajolida's avatar
sajolida committed
122

sajolida's avatar
sajolida committed
123 124 125 126 127 128 129 130 131 132 133 134 135 136
- **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
137
  - *For example*:
sajolida's avatar
sajolida committed
138 139 140 141 142 143 144 145 146

<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
147 148 149 150 151 152
- **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.

153 154 155
- **persistence feature**

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

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

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

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

167 168 169 170 171
- **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).

172 173 174 175 176 177
- **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
178 179 180 181 182
- **startup options**

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

sajolida's avatar
sajolida committed
183 184 185 186
  - *For example:*

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

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

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

sajolida's avatar
sajolida committed
192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
- **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
213 214 215
- **vulnerability** or **security vulnerability**

  And not *hole* or *issue*.