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:
- 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.
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
- Code:
- span.button for button names, for example:
- Code:
the <span class="button">Login</span> button - Result: the button
- Code:
- span.code for code excerpts, for example:
- Code:
<span class="code">id="tails-greeter"</span> - Result: id="tails-greeter"
- Code:
- span.command for command names
- Code:
the <span class="command">apt-get</span> command - Result: the apt-get command
- Code:
- span.filename for file names, for example:
- Code:
the <span class="filename">~/.gnupg/gpg.conf</span> file - Result: the ~/.gnupg/gpg.conf file
- Code:
- span.guilabel for GUI label, for example:
- Code:
<span class="guilabel">Enter passphrase</span> - Result: Enter passphrase
- Code:
- span.menuchoice, span.guimenu, span.guisubmenu, span.guimenuitem for menu
and menu items, for example:
- Code:
<span class="menuchoice"> <span class="guimenu">Applications</span> ▸ <span class="guisubmenu">Tails</span> ▸ <span class="guimenuitem">Configure persistent storage</span> </span> - Result:
- Code:
- span.keycap for
- Code:
the <span class="keycap">Tab</span> key - Result: the Tab key
- Code:
- span.replaceable
- Code:
<span class="command">select disk=<span class="replaceable">number</span></span> - Result: select disk=number
- Code:
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:
Next
Provides links to other related sections of the documentation that might be interesting to read next. For example:
Related online resources
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.org, Webopedia.com, Whatis.com can be used as terminology websites for technical terms.