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-get</span> command
    • Result: the apt-get 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.

https://developer.gnome.org/gdp-style-guide/stable/infodesign-18.html.en

Bugs

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 Iceweasel Web Browser nor with the Unsafe Web Browser.

Next

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

Related online resources