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.
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:
- 2.4.2. Guidelines for Using Screenshots in Online Help explains how to decide to use screenshots.
- 4. Writing documentation for an International Audience includes specific rules about how to write documentation that is easier to translate, with practical examples.
- 5.2. Checks You Can Do Yourself lists the top ten topics that you need to watch out for when you review your work.
- A. Recommended Terminology contains a glossary of terms for use when writing documentation.
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.
Use the equivalent of DocBook tags to style your documentation using CSS.
- span.application for application names, for example:
<span class="application">Tails Greeter</span>
- Result: Tails Greeter
- span.button for button names, for example:
the <span class="button">Login</span> button
- Result: the button
- span.code for code excerpts, for example:
- Result: id="tails-greeter"
- span.command for command names
the <span class="command">apt-get</span> command
- Result: the apt-get command
- span.filename for file names, for example:
the <span class="filename">~/.gnupg/gpg.conf</span> file
- Result: the ~/.gnupg/gpg.conf file
- span.guilabel for GUI label, for example:
<span class="guilabel">Enter passphrase</span>
- Result: Enter passphrase
- span.menuchoice, span.guimenu, span.guisubmenu, span.guimenuitem for menu
and menu items, for example:
<span class="menuchoice"> <span class="guimenu">Applications</span> ▸ <span class="guisubmenu">Tails</span> ▸ <span class="guimenuitem">Configure persistent storage</span> </span>
- span.keycap for
the <span class="keycap">Tab</span> key
- Result: the Tab key
<span class="command">select disk=<span class="replaceable">number</span></span>
- Result: select disk=number
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:
You can also decrypt or verify a text that is encrypted or signed using public-key cryptography using OpenPGP Applet.
Jakob Nielsen's How Users Read on the Web and Be Succinct - Writing for the Web. However do not use bold for scanning in instruction steps. Steps should be short enough and bold mixes up with other GUI formatting.
Wikipedia Manual of Style is another useful resource on writing, typography, punctuation, etc.