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">Tails Greeter</span>
    • Result: Tails Greeter
  • 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:

About screenshots

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

We always compress screenshots using compress-image.



Ikiwiki shortcuts

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

Related online resources