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

sajolida's avatar
sajolida committed
3
- **bulleted lists**
4 5 6 7

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

cbrownstein's avatar
cbrownstein committed
8
- **Debian and Ubuntu versions**
sajolida's avatar
sajolida committed
9

cbrownstein's avatar
cbrownstein committed
10 11
  Refer to Debian and Ubuntu versions primarily by their numbers, and additionally
  by their codenames.
sajolida's avatar
sajolida committed
12

sajolida's avatar
sajolida committed
13 14 15
  * *For example*:
    - Tails 3.0 is based on Debian 9 (Stretch)
    - *Tails Installer* is available on Ubuntu 15.10 (Wily Werewolf) or later.
16

sajolida's avatar
sajolida committed
17 18
<a id="digit_grouping"></a>

19 20
- **digit grouping**

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

  * *For example*:
sajolida's avatar
sajolida committed
25
    - $50&#8239;000
26 27 28

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

30
<a id="gnome_application"></a>
31

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

34 35
  GNOME applications that have a common noun as their name (like
  <span class="application">Files</span> or
cbrownstein's avatar
cbrownstein committed
36
  <span class="application">Disks</span>) can be confusing when referred
37
  to in the documentation.
38

39
  Make sure to clarify that you are referring to an application (and
cbrownstein's avatar
cbrownstein committed
40
  not, for example, a set of files or disks):
41 42 43 44 45 46 47 48 49 50 51 52 53

  - *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 their short name as it appears in the menus when giving
  instructions to be executed inside Tails.

  - *For example*:
54 55
    - Open */live/persistence/TailsData_unlocked/dotfiles* in *Files*.

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

59 60
  - *For example*:
    - Install <span class="application">GNOME Disks</span> in Debian.
61

sajolida's avatar
sajolida committed
62 63
- **graphics card**

64 65
  And not *graphics adapters*, *graphics*, *graphical hardware*, or
  *video card*.
sajolida's avatar
sajolida committed
66

sajolida's avatar
sajolida committed
67 68 69 70 71 72
- **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.

73 74 75 76 77 78 79 80 81 82 83
- **persistence feature**

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

  - *For example*: when the <span class="guilabel">Additional
    Software</span> persistence feature is activated.

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

84 85 86 87 88 89
- **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
90 91 92 93 94 95 96
- **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]].
97

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

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