[[!meta title="Documentation style guide"]]
- **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]].
- **anchors** (HTML anchors)
Use HTML anchors to provide shortcuts when pointing people to sections
inside a page.
- *For example*:
- `` 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.
- **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 Loader* when referring to either *GRUB* or *SYSLINUX*.
- *For example:*
- The Boot Loader is the first screen that appears when starting Tails.
- 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 toram
boot option in the Boot Loader
Menu. For detailed instructions, see the documentation on
[[using the Boot Loader
Menu|doc/first_steps/startup_options#boot-loader]].
- To make the display work properly, [[add the following boot option
when starting Tails|doc/first_steps/startup_options/#boot-loader]]:
nouveau.noaccel=1
- **bulleted lists**
Refer to this article from NN/g on [presenting bulleted
lists](https://www.nngroup.com/articles/presenting-bulleted-lists/).
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.
- **Debian and Ubuntu versions**
Refer to Debian and Ubuntu versions primarily by their numbers, and additionally
by their codenames.
- *For example*:
- Tails 3.0 is based on Debian 9 (Stretch)
- *Tails Installer* is available on Ubuntu 15.10 (Wily Werewolf) or later.
- **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.**.
- *For example:*
- If you are running macOS 10.10 (Yosemite) or earlier
- **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.
- **digit grouping**
Use a non-breaking thin space (HTML entity: ` `) or a space to separate
groups of three digits.
- *For example*:
- $50 000
See [[!wikipedia Decimal_separator#Digit_grouping]] and [[!wikipedia
ISO_31-0#Numbers]].
- **GNOME applications: Files, Disks, etc.**
GNOME applications that have a common noun as their name (like
Files or
Disks) can be confusing when referred
to in the documentation.
Make sure to clarify that you are referring to an application (and
not, for example, a set of files or disks):
- *For example*:
- In the title of sections
- When first referring to the application in a section
- *Use*:
- The Files browser
- The Disks utility
Otherwise, use the short name of the application as it appears in the menus when giving
instructions to be executed inside Tails.
- *For example*:
- Open */live/persistence/TailsData_unlocked/dotfiles* in *Files*.
Prepend "*GNOME*" when giving instructions to be executed outside of
Tails.
- *For example*:
- Install GNOME Disks in Debian.
- **graphics card**
And not *graphics adapters*, *graphics*, *graphical hardware*, or
*video card*.
- **Internet**
Capitalize. When used as a noun, always preceded by *the*.
- **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.
- **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.
- **persistence feature**
To refer to the features available in the configuration of the
*persistent storage*.
- *For example*:
- […] when the [[Additional Software
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]]).
- **please**
Avoid please except in situations where the user is asked to do
something inconvenient or the software is to blame for the situation.
- **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*.
- *For example*:
1. Make sure that you are connected to the Internet.
1. Start Software Sources.
1. Click on the PPAs button and then choose to Add a new PPA….
- **right-click**
Trackpads on Mac have a single button. Control-click, the usual way of
doing right-click on Mac, does something different in Tails (and
Windows): it is used to select multiple items.
Always clarify how to do right-click on Mac:
- *For example:*
- Right-click (on Mac, click with two fingers) on the file and
choose .
- **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).
- **serial comma**
Place a [[!wikipedia serial comma]] immediately before the
coordinating conjunction (usually *and* or *or*) in a series of three
or more terms.
- **Tails Greeter**
Without an article. Not *the Greeter*. Note the formatting as an application.
- **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.
- 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.
- **vulnerability** or **security vulnerability**
And not *hole* or *issue*.