• 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 hyphens instead of underscores to separate words.

    For example:

    • <a id="2014"> in doc/about/finances to be able to point to https://tails.boum.org/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 will automatically reference it 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.

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

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

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

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

  • 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 on Create & configure the Persistent Storage.

    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.

    2. Start Software Sources.

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

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

  • Tails session

    The time between starting Tails and shutting it down.

  • Welcome Screen

    With an article. Not Tails Greeter or the Greeter.

  • 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, bug, issue, or exploit.