summaryrefslogtreecommitdiffstats
path: root/wiki/src/contribute/how/documentation/style_guide.mdwn
diff options
context:
space:
mode:
Diffstat (limited to 'wiki/src/contribute/how/documentation/style_guide.mdwn')
-rw-r--r--wiki/src/contribute/how/documentation/style_guide.mdwn64
1 files changed, 52 insertions, 12 deletions
diff --git a/wiki/src/contribute/how/documentation/style_guide.mdwn b/wiki/src/contribute/how/documentation/style_guide.mdwn
index d5c1e69..76954f1 100644
--- a/wiki/src/contribute/how/documentation/style_guide.mdwn
+++ b/wiki/src/contribute/how/documentation/style_guide.mdwn
@@ -27,27 +27,67 @@
See [[!wikipedia Decimal_separator#Digit_grouping]] and [[!wikipedia
ISO_31-0#Numbers]].
-- **<i>Files</i>**, **<i>Disks</i>**, etc.
+<a id="gnome_application"></a>
- To refer to GNOME applications:
+- **GNOME applications: <i>Files</i>, <i>Disks</i>, etc.**
- - Use their short name as it appears in the menus when giving
- instructions to be executed inside Tails.
+ GNOME applications that have a common noun as their name (like
+ <span class="application">Files</span> or
+ <span class="application">Disks</span>) can be confusing when referred
+ to in the documentation.
- *For example*:
+ Make sure to clarify that you are referring to an application (and
+ not, for example, a set of files or disks):
+
+ - *For example*:
+ - In the title of sections
+ - When first referring to the application in a section
+
+ - *Use*:
+ - The <span class="application">Files</span> browser
+ - The <span class="application">Disks</span> utility
+
+ Otherwise, use the short name of the application as it appears in the menus when giving
+ instructions to be executed inside Tails.
+
+ - *For example*:
- Open */live/persistence/TailsData_unlocked/dotfiles* in *Files*.
- - Prepend "*GNOME*" when giving instructions to be executed outside of
- Tails.
+ Prepend "*GNOME*" when giving instructions to be executed outside of
+ Tails.
- *For example*:
- - Install GNOME Disks in Debian.
+ - *For example*:
+ - Install <span class="application">GNOME Disks</span> in Debian.
- **graphics card**
And not *graphics adapters*, *graphics*, *graphical hardware*, or
*video card*.
+- **procedures** (a series of steps)
+
+ - Keep the number of steps low within a procedure (for example, below
+ 10, ideally 7). For longer procedures, split them and give each
+ section a title.
+
+ - Add a blank line between each step.
+
+ - Rely on the automatic numbered of Markdown and number all the steps
+ with `1.`
+
+ See also the *Microsoft Manual of Style: Procedures and technical
+ content*.
+
+ *For example*:
+
+<pre>
+1. Make sure that you are connected to the Internet.
+
+1. Start <span class="application">Software Sources</span>.
+
+1. Click on the <span class="guilabel">PPAs</span> button and then choose to <span class="button">Add a new PPA&hellip;</span>.
+</pre>
+
- **network interface**, **Wi-Fi interface**
And not *card*, *device*, or *adapter*.
@@ -57,10 +97,10 @@
- **persistence feature**
To refer to the features available in the configuration of the
- *persistent volume*.
+ *persistent storage*.
- - *For example*: when the <span class="guilabel">Additional
- Software</span> persistence feature is activated.
+ - *For example*: when the [[<span class="guilabel">Additional
+ Software</span> persistence feature|doc/first_steps/persistence/configure#additional_software]] is activated.
The word *persistence* can be omitted if it is redundant from the context
(for example on [[doc/first_steps/persistence/configure]]).