summaryrefslogtreecommitdiffstats
path: root/wiki/src/contribute/how/documentation/guidelines.mdwn
blob: 63e3cfb2e43d8f1d182459a1935912ad69ba94b0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
[[!meta title="Documentation guidelines"]]

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.

[[!toc levels=2]]

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.

  - [GNOME Documentation Style Guide](http://developer.gnome.org/gdp-style-guide/2.32/),
  - [GNOME Documentation Style Guide, single HTML
    file](http://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html)

**Read at least [Section 1 ― Fundamental Concepts of Technical
Documentation](http://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html#fundamentals).**

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](http://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html#infodesign-10)
    explains how to decide to use screenshots.
  - [4. Writing documentation for an International
    Audience](http://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html#locale)
    includes specific rules about how to write documentation that is
    easier to translate, with practical examples.
  - [5.2. Checks You Can Do
    Yourself](http://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html#improving-6)
    lists the top ten topics that you need to watch out for when you
    review your work.
  - [A. Recommended
    Terminology](http://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html#wordlist)
    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](https://en.wikipedia.org/wiki/Wikipedia:Naming_conventions_%28capitalization%29).
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](http://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html#grammar)
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 class="code">span.application</span> for application names, for example:
    - Code: `<span class="application">Tails Greeter</span>`
    - Result: <span class="application">Tails Greeter</span>
  - <span class="code">span.button</span>  for button names, for example:
    - Code: `the <span class="button">Login</span> button`
    - Result: the <span class="button">Login</span> button
  - <span class="code">span.code</span>  for code excerpts, for example: 
    - Code: `<span class="code">id="tails-greeter"</span>`
    - Result: <span class="code">id="tails-greeter"</span>
  - <span class="code">span.command</span>  for command names
    - Code: `the <span class="command">apt-get</span> command`
    - Result: the <span class="command">apt-get</span> command
  - <span class="code">span.filename</span>  for file names, for example:
    - Code: `the <span class="filename">~/.gnupg/gpg.conf</span> file`
    - Result: the <span class="filename">~/.gnupg/gpg.conf</span> file
  - <span class="code">span.guilabel</span> for GUI label, for example:
    - Code: `<span class="guilabel">Enter passphrase</span>`
    - Result: <span class="guilabel">Enter passphrase</span>
  - <span class="code">span.menuchoice</span>, <span class="code">span.guimenu</span>, <span class="code">span.guisubmenu</span>, <span class="code">span.guimenuitem</span> for menu
    and menu items, for example:
    - Code:<br/>
      `<span class="menuchoice">
        <span class="guimenu">Applications</span>&nbsp;▸
        <span class="guisubmenu">Tails</span>&nbsp;▸
        <span class="guimenuitem">Configure persistent storage</span>
      </span>`
    - Result: <span class="menuchoice">
      <span class="guimenu">Applications</span>&nbsp;▸
        <span class="guisubmenu">Tails</span>&nbsp;▸
	  <span class="guimenuitem">Configure persistent
	  storage</span></span>
  - <span class="code">span.keycap</span> for 
    - Code: `the <span class="keycap">Tab</span> key`
    - Result: the <span class="keycap">Tab</span> key
  - <span class="code">span.replaceable</span>
    - Code: `<span class="command">select disk=<span class="replaceable">number</span></span>`
    - Result: <span class="command">select disk=<span class="replaceable">number</span></span>

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/2.32/infodesign-18.html.en>

Bugs
----

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

<div class="bug">

The screen reading functionality of <span class="application">GNOME
Orca</span> does not work neither with the <span
class="application">Tor Browser</span> nor with the <span
class="application">Unsafe Web Browser</span>.

</div>

Next
----

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

<div class="next">

You can also
[[decrypt or verify a text that is encrypted or signed using public-key cryptography|doc/encryption_and_privacy/gpgapplet/decrypt_verify]]
using <span class="application">OpenPGP Applet</span>.

</div>

Ikiwiki shortcuts
=================

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

Related online resources
========================

- Jakob Nielsen's
  [How Users Read on the Web](http://www.nngroup.com/articles/how-users-read-on-the-web/)
  and [Be Succinct - Writing for the Web](http://www.nngroup.com/articles/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](https://en.wikipedia.org/),
  [Webopedia.com](http://www.webopedia.com),
  [Whatis.com](http://whatis.com) can be used as terminology websites
  for technical terms.

- [Wikipedia Manual of Style](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style)
  is another useful resource on writing, typography, punctuation, etc.