This page contains guidelines and resources for writing documentation for Tails. Most of these rules can also be applied when writing graphical user interfaces. Doing so helps creating a consistent language across GUI and documentation.

Follow the GNOME Documentation Style Guide

The GNOME Documentation Style Guide (GDSG) provides guidelines for authors who want to contribute to the GNOME Documentation Project (GDP). Try to follow those guidelines when writing documentation and GUI for Tails.

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:

Use title capitalization rules from Wikipedia

Do not use the capitalization rules for headings from the GDSG. Use instead the sentence-style capitalization rules from Wikipedia. In short, do not capitalize the second or subsequent words in an article title, unless the title is a proper noun. Sentence-style capitalization looks less formal and is also easier for the worldwide audience to read.

But use title capitalization, as described in GDSG section 3. Grammar and Usage Guidelines for the names of GUI items: buttons, dialogs, applications, menus, etc.

CSS formating for GUI documentation

Use the equivalent of DocBook tags to style your documentation using CSS.

  • span.application for application names, for example:
    • Code: <span class="application">Welcome Screen</span>
    • Result: Welcome Screen
  • span.button for button names, for example:
    • Code: the <span class="button">Login</span> button
    • Result: the Login button
  • span.code for code excerpts, for example:
    • Code: <span class="code">id="tails-greeter"</span>
    • Result: id="tails-greeter"
  • span.command for command names
    • Code: the <span class="command">apt</span> command
    • Result: the apt command
  • span.filename for file names, for example:
    • Code: the <span class="filename">~/.gnupg/gpg.conf</span> file
    • Result: the ~/.gnupg/gpg.conf file
  • span.guilabel for GUI label, for example:
    • Code: <span class="guilabel">Enter passphrase</span>
    • Result: Enter passphrase
  • span.menuchoice, span.guimenu, span.guisubmenu, span.guimenuitem for menu and menu items, for example:
    • Code:
      <span class="menuchoice"> <span class="guimenu">Applications</span>&nbsp;▸ <span class="guisubmenu">Tails</span>&nbsp;▸ <span class="guimenuitem">Configure persistent storage</span> </span>
    • Result: Applications ▸ Tails ▸ Configure persistent storage
  • span.keycap for
    • Code: the <span class="keycap">Tab</span> key
    • Result: the Tab key
  • span.replaceable
    • Code: <span class="command">select disk=<span class="replaceable">number</span></span>
    • Result: select disk=number

Tips, notes, cautions, bugs, and next

Use tips, notes, and cautions to highlight important information, as described in the GNOME Documentation Style Guide.


Provides information about important bugs that affect the software which is described in its principal use cases. For example:

The screen reading functionality of GNOME Orca does not work neither with the Tor Browser nor with the Unsafe Web Browser.


Provides links to other related sections of the documentation that might be interesting to read next. For example:


We limit the number of screenshots in the documentation to the minimum. The GNOME Documentation Style Guide explains very well the disadvantages of screenshots.

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.

We also most of the time resize the screenshots to 66%, either when they are too big or when they can be confused for the actual application (see #11527). Use the NoHalo interpolation in GIMP.

We always 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 Inkscape:

  1. Create the base screenshot, resized at 66%.
  2. Open it in Inkspace.
  3. Create a red circle or rectangle with a width of 2 px.
  4. Export the screenshot to PNG, respecting it's original size.

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.

Ikiwiki shortcuts

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

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.

Related online resources