Introduction

We use this style guide to keep our documentation clear, consistent, and accessible to a global audience. Apply this style guide when writing new documentation or when updating existing documentation.

Reference hierarchy

Use references in the following order:

  1. This style guide.

  2. The GNOME Documentation Style Guide.

    Read at least Section 1 ― Fundamental Concepts of Technical Documentation.

    The following sections are also of particular interest or have been debated within Tails before:

  3. Other style guides:

We use US spelling. For spelling of words, we use the Merriam-Webster dictionary.

The following resources can also be helpful when writing documentation for Tails:

Related online resources

Style and usage

  • alt attributes for images

    The alt attribute of an image is, for example, read by screen readers in place of images allowing the content and function of the image to be accessible to those with visual or certain cognitive disabilities.

    Every image must have an alt attribute but it can be empty (alt="").

    In the case of our documentation:

    • Often screenshots require no additional information to clarify their content. They often provide visual context that is useful for people who see them but not necessary to people who don't see them.

    • For graphical buttons or icons, use as alt attribute the text that is read by the GNOME Screen Reader (or that you think should be read if none is read). For example:

      1. Click on the <span class="guimenu">
[[!img  lib/unlock.png alt="Unlock" class="symbolic" link="no"]]
</span> button.

    For more guidelines and examples about writing good alt attributes, read the article on alternative text by WebAIM.

  • anchor (HTML anchor)

    Use HTML anchors to provide shortcuts when pointing people to sections inside a page.

    Keep them as short as possible as they appear in the URL.

    Use lowercase and underscore to separate words.

    For example:

    • <a id="2014"> in doc/about/finances to be able to point to https://tails.net/finances#2014.

    When adding an anchor to a section on a page that has a table of content, add the id attribute directly to the HTML heading. ikiwiki automatically references this anchor in the table of content instead of the default value that might change over time.

    For example:

    • [[!toc ]]
<h1 id="my_section">My section</h1>

      Creates a hyperlink to #my_section in the table of content instead of a hyperlink to #index1h1 that might change with the structure of the page.

    To reduce translation work, avoid adding anchors to translated pages when we are not using them anywhere on the website.

  • boot vs start

    Use start and restart as much as possible to refer to starting a computer on Tails; boot is almost always unnecessary 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:

  • Boot Menu and Boot Loader

    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 Menu and Boot Menu key when referring to the BIOS screen that allows choosing from which device to start from.

  • bulleted lists

    Refer to this article from NN/g on 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.

  • capitalization

    • Use sentence case for titles and headings

      Do not capitalize the second or subsequent words, unless they are proper nouns. Sentence case looks less formal and is easier to read for a global audience.

      See the capitalization rules from Wikipedia.

    • Use title case for GUI items

      Buttons, dialogs, applications, menus, etc.

  • Code excerpts and error messages

    To write an entire paragraph as code that cannot wrap and stop interpreting HTML within it, use either:

    • 4 spaces as indentation, like in Markdown

    • <pre>

    To write an entire paragraph as code that can wrap and keep interpreting HTML within it, use:

    • <p class="code">

    To write only some words as code and stop interpreting HTML within them, use either:

    • Backticks (`), like in Markdown

    • <code>

    To write only some words as code and keep interpreting HTML within them, use:

    • <span class="code">

  • Command lines

    To write a command line as an entire paragraph that can be selected and copied, use:

    • <p class="command">

      Such a command line cannot wrap to make it clear to the reader that it has to be executed as a single command line.

    To write a command line template as an entire paragraph that cannot be selected and copied, use:

    • <p class="command-template">

      Such a command line cannot be selected to prevent the reader from executing it as such.

    Within a command line template, delimit the placeholders that have to be replaced by the reader with:

    • <span class="command-placeholder">

    To write a command line that has to be executed as root, use:

    • <p class="command-root">

    You can combine these different classes.

    Explain how to replace the placeholders before giving out the full comman line.

    For example:

    • Markdown:

      Execute the following commands to install a new package. Replace
<span class="command-placeholder">package</span> with the package that
you want to install.

<p class="command-template command-root">
apt install <span class="command-placeholder">package</span>
</p>

    • Result:

      Execute the following commands to install a new package. Replace package with the package that you want to install.

      apt install package

  • CSS formatting for documentation

    Use the following Markdown and HTML to style your documentation using CSS.

    • Features

      Capitalize the name of major features of Tails.

      For example:

      • Welcome Screen

      • Persistent Storage

    • Application and file names

      Write in italic the names of files and GUI applications other than Tails.

      Write as code the names of command line applications.

      For example:

      • Markdown: *Thunderbird*

      • HTML: <i>Thunderbird</i>

      • Result: Thunderbird

      For example:

      • Markdown: *~/.gnupg/gpg.conf*

      • HTML: <i>~/.gnupg/gpg.conf</i>

      • Result: ~/.gnupg/gpg.conf

      For example:

      • Ping: ping

      • HTML: <code>ping</code>

      • Result: ping

    • Button names, GUI labels, key caps, and menu items

      Write in bold button names, GUI labels, key caps, and menu items, especially in procedures.

      For example:

      • Markdown: Click **Save**.

      • HTML: Click <b>Save</b>.

      • Result: Click Save.

      In documentation, do not a not add the elipsis of the button label to indicate that a dialog box will appear.

      For example:

      • Markdown: Choose **Applications&nbsp;▸ Tor Browser**

      • HTML: Choose <b>Applications&nbsp;▸ Tor Browser</b>

      • Result: Choose Applications ▸ Tor Browser

  • Debian and Ubuntu versions

    Refer to Debian and Ubuntu versions primarily by their number, 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.

  • 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.

  • Image compression

    • Images on our website are compressed and cleaned using the compress-image.sh script. To run this script you need the zopfli and mat2 packages.

  • Internet

    Capitalize. When used as a noun, always preceded by the.

  • Ikiwiki shortcuts

    The [[!tails_ticket ..]] and [[!wikipedia ..]] strings you can find in some files are ikiwiki shortcuts. You might also need to understand ikiwiki directives.

  • MAC address anonymization

    And not MAC address spoofing, or MAC spoofing.

    We're still using MAC spoofing in internal and design documentation because it's common tech jargon.

  • 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.

  • might, may, can

    Use might to express possibility.

    Only use may to express permission.

    Use can to express ability.

    Only use could to refer to the past.

    See Microsoft Style Guide: can, may.

  • 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.

  • Persistent Storage

    And not persistence or persistent volume. Capitalize. Can be introduced by your, the, a or no article depending on the context.

    The Persistent Storage refers to both the feature and the encrypted volume on the USB stick.

    In rare occasions, we write encrypted Persistent Storage, for example when introducing the concept. Otherwise, we rely on the interface of the Welcome Screen to remind people that it is encrypted.

    The Persistent Storage is created using the Persistent Storage settings and unlocked in the Welcome Screen.

    For example:

    • Create a Persistent Storage on your Tails USB stick.

    • Enter your passphrase to unlock your Persistent Storage.

    • Everything in the Persistent Storage is encrypted automatically.

    • Add To Persistent Storage (button)

  • Persistent folder

    The folder /home/amnesia/Persistent/.

    For example:

    • Save the database as keepassx.kdbx in the Persistent folder.

  • feature of the Persistent Storage

    And not Persistent Storage feature.

    To refer to the features available in the configuration of the Persistent Storage.

    The construction of the Persistent Storage can be omitted if redundant in the context.

    For example:

    • To install additional software automatically when starting Tails, turn on the Additional Software feature of the Persistent Storage.

  • persistent and persist

    The property of something saved in the Persistent Storage and the act of making something persistent. Use rarely.

    For example:

    • The Persistent Storage is optional and you always decide what is persistent. Everything else is amnesic.

  • 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...**.

  • QR codes

    • To encode and decode QR codes, you can use the qrcode-encode.sh and qrcode-decode.sh scripts. To run these scripts you need to install the qrencode and zbar-tools packages.

      For example (run from Tails' source root):

      wiki/src/contribute/how/documentation/qrcode-encode.sh https://tails.net/

      Creates a QR code in tails_net.png. And:

      wiki/src/contribute/how/documentation/qrcode-decode.sh tails_net.png

      Outputs:

      QR-Code:https://tails.net/

  • 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 Share via OnionShare.

  • Screenshots

    Use screenshots only when they provide useful additional information to complete the text. The text should be enough to follow our documentation but screenshots might help provide context, engage the reader, or support a complex procedure.

    We limit the number of screenshots to the minimum because they take time to produce, they need frequent update, are harder to translate, and are not accessible.

    When using screenshots of full windows, we include the window decoration and a border of blue background to clarify the context and the nature of the image. To take such a screenshot:

    1. In Gimp choose File ▸ Create ▸ Screenshot.

    2. Select Include windows decoration.

    3. Make sure the blue border (0x204a87) on each side of the screenshot is at least 18px.

    Use the screenshot CSS class to add a gray shadow under the screenshot and help distinguish them from the actual application.

    [[!img  screenshot-good.png link="no" class="screenshot" alt=""]]

    Most often, screenshots are not necessary to follow instructions and can have an empty alt tag. Screenshots that describe new features, usually benefit from an alt tag that describes what is new.

    Compress screenshots using compress-image.

    When an element of a screenshot needs to be highlighted, for example because the element is small, has no label or is in a place that is hard to describe, highlight it in red using Gimp:

    1. Create the base screenshot.

    2. Create a new layer for the highlighting.

    3. Create a red circle or rectangle with:

      • Red color #ef1f31
      • Width of 3 px
      • Margin of 3 px with the highlighted element

    Good:

    Bad:

    If the full size screenshot is too big, in the img directive:

    • Check if the automatic resizing from local.css to max-width: 100% is enough already.

    • Use the size="" attribute to resize it even more, if needed.

    • Do not specify any link="" attribute to add a link to the full size image, if that's useful.

  • 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 serial comma immediately before the coordinating conjunction (usually and or or) in a series of three or more terms.

  • SVG images

    SVG are easier to maintain and look great on all screen sizes, but they are not displayed in the Safest security level of Tor Browser. (#17805)

    Because of that, we don't use SVG images by default. Instead, do the following:

    1. Export SVG images to PNG at the same size as they would be displayed on a large screen.

    2. Compress the PNG image.

    3. Store the SVG source side-by-side with its PNG version, to ease future modifications.

    4. For the bigger and more significant images that could benefit from the additional quality of SVG on bigger screens, you can add class="svg" to the image so that wiki/src/lib/js/local.js replaces it with the SVG version whenever JavaScript is available.

      [[!img  city.png link="no" class="svg" alt=""]]

  • your Tails

    Use to refer to the installation of the operating system of the user.

    Use your Tails USB stick when it's useful to refer to the physical medium more explicitly.

    For example:

    • A virus in Windows could corrupt your Tails.

    • Plug your Tails USB stick into your computer.

  • Tails session

    The time between starting Tails and shutting it down.

  • Tails versions

    Refer to Tails versions by their number. Optionally mention the month and year of the release when it might help users evaluate the relevance of an information, for example when mentioning important changes in a past version.

    For example:

    • Tails 1.1 does not start in some virtualization environments.

    • Tails does not work on 32-bit computers since Tails 3.0 (June 2017).

  • Tips, notes, cautions, bugs, and next

    Use tips, notes, and cautions to highlight important information.

    • Tip:

      <div class="tip">

<p>This tip could be useful to some readers.</p>

</div>

      This tip could be useful to some readers.

    • Note:

      <div class="note">

<p>This note attracts attention.</p>

</div>

      This note attracts attention.

    • Caution:

      <div class="caution">

<p>This warning describes something dangerous.</p>

</div>

      This warning describes something dangerous.

    • Bug:

      <div class="bug">

<p>This bug describes an important flaw of the software.</p>

</div>

      This bug describes an important flaw of the software.

    • Next:

      <div class="next">

<p>This note helps to know what to read next.</p>

</div>

    • Attack:

      <div class="attack">

<p>This note decribes a security attack and its likelihood.</p>

</div>

      This note decribes a security attack and its likelihood.

  • 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.

  • USB stick

    And not USB drive, USB, thumb drive, or flash drive.

  • vulnerability or security vulnerability

    And not hole, bug, issue, or exploit.

  • Welcome Screen

    With an article. Not Tails Greeter or the Greeter.

  • Wrap to 80 characters but only when needed

    New documentation should be wrapped to 80 characters. However, please do not submit patches that merely re-wrap existing text, as this makes it harder to read the Git history.