wiki/src/contribute/how/documentation/style_guide.mdwn

   1 [[!meta title="Documentation style guide"]]
   2
   3 - **bulleted lists**
   4
   5   Refer to this article from NN/g on [presenting bulleted
   6   lists](https://www.nngroup.com/articles/presenting-bulleted-lists/).
   7
   8   Always add empty lines between list items to:
   9
  10   - Make them easier to read.
  11
  12   - Make them easier to translate. Each item from the list will be put
  13     in a separate PO string in PO files by the PO plugin when building
  14     the website.
  15
  16 - **Debian and Ubuntu versions**
  17
  18   Refer to Debian and Ubuntu versions primarily by their numbers, and additionally
  19   by their codenames.
  20
  21   - *For example*:
  22
  23     - Tails 3.0 is based on Debian 9 (Stretch)
  24
  25     - *Tails Installer* is available on Ubuntu 15.10 (Wily Werewolf) or later.
  26
  27 <a id="digit_grouping"></a>
  28
  29 - **digit grouping**
  30
  31   Use a non-breaking thin space (HTML entity: `&#8239;`) or a space to separate
  32   groups of three digits.
  33
  34   - *For example*:
  35
  36     - $50&#8239;000
  37
  38   See [[!wikipedia Decimal_separator#Digit_grouping]] and [[!wikipedia
  39   ISO_31-0#Numbers]].
  40
  41 <a id="gnome_application"></a>
  42
  43 - **GNOME applications: <i>Files</i>, <i>Disks</i>, etc.**
  44
  45   GNOME applications that have a common noun as their name (like
  46   <span class="application">Files</span> or
  47   <span class="application">Disks</span>) can be confusing when referred
  48   to in the documentation.
  49
  50   Make sure to clarify that you are referring to an application (and
  51   not, for example, a set of files or disks):
  52
  53   - *For example*:
  54
  55     - In the title of sections
  56
  57     - When first referring to the application in a section
  58
  59   - *Use*:
  60
  61     - The <span class="application">Files</span> browser
  62
  63     - The <span class="application">Disks</span> utility
  64
  65   Otherwise, use the short name of the application as it appears in the menus when giving
  66   instructions to be executed inside Tails.
  67
  68   - *For example*:
  69
  70     - Open */live/persistence/TailsData_unlocked/dotfiles* in *Files*.
  71
  72   Prepend "*GNOME*" when giving instructions to be executed outside of
  73   Tails.
  74
  75   - *For example*:
  76
  77     - Install <span class="application">GNOME Disks</span> in Debian.
  78
  79 - **graphics card**
  80
  81   And not *graphics adapters*, *graphics*, *graphical hardware*, or
  82   *video card*.
  83
  84 - **procedures** (a series of steps)
  85
  86   - Keep the number of steps low within a procedure (for example, below
  87     10, ideally 7). For longer procedures, split them and give each
  88     section a title.
  89
  90   - Add a blank line between each step.
  91
  92   - Rely on the automatic numbered of Markdown and number all the steps
  93     with `1.`
  94
  95   See also the *Microsoft Manual of Style: Procedures and technical
  96   content*.
  97
  98   - *For example*:
  99
 100 <pre>
 101 1. Make sure that you are connected to the Internet.
 102
 103 1. Start <span class="application">Software Sources</span>.
 104
 105 1. Click on the <span class="guilabel">PPAs</span> button and then choose to <span class="button">Add a new PPA&hellip;</span>.
 106 </pre>
 107
 108 - **network interface**, **Wi-Fi interface**
 109
 110   And not *card*, *device*, or *adapter*.
 111
 112   Still, **USB Wi-Fi adapters** are USB dongles that provide a Wi-Fi interface.
 113
 114 - **persistence feature**
 115
 116   To refer to the features available in the configuration of the
 117   *persistent storage*.
 118
 119   - *For example*:
 120
 121     - [&hellip;] when the [[<span class="guilabel">Additional Software</span>
 122       persistence feature|doc/first_steps/persistence/configure#additional_software]]
 123       is activated.
 124
 125   The word *persistence* can be omitted if it is redundant from the context
 126   (for example on [[doc/first_steps/persistence/configure]]).
 127
 128 - **Secure Boot**
 129
 130   Capitalize as a brand or feature. Writing *secure boot* would make it
 131   sound more like a magic security feature (which it is not).
 132
 133 - **serial comma**
 134
 135   Place a [[!wikipedia serial comma]] immediately before the
 136   coordinating conjunction (usually *and* or *or*) in a series of three
 137   or more terms.
 138
 139 - **startup options**
 140
 141   To refer to the kernel command line options that can be specified from
 142   the *Boot Loader Menu*.
 143
 144   - *For example:*
 145
 146     - Adding `radeon.dpm=0` to the [[startup
 147       options|/doc/first_steps/startup_options#boot_menu]].
 148
 149 - **<span class="application">Tails Greeter</span>**
 150
 151   Without an article. Not *the Greeter*. Note the formatting as an application.
 152
 153 - **vulnerability** or **security vulnerability**
 154
 155   And not *hole* or *issue*.