Commit d6676c68 authored by sajolida's avatar sajolida
Browse files

Merge branch 'doc/16345-style-guide'

parents 7e52827c 7a7523c6
[[!meta title="Documentation style guide"]]
- **administration password** vs **root password**
Use *administration password*. Avoid *root password* even though many
Linux users would use it.
- *For example:*
- [[Set up an administration password
|doc/first_steps/startup_options/administration_password]] when
you start Tails.
- Start Tails and [[set up an administration
password|doc/first_steps/startup_options/administration_password]].
- **anchors** (HTML anchors)
Use HTML anchors to provide shortcuts when pointing people to sections
inside a page.
- *For example*:
- `<a id="2014">` in `doc/about/finances` to be able to point to
`https://tails.boum.org/finances#2014`.
- Keep them as short as possible as they appear in the URL.
- Use hyphens instead of underscores to separate words.
- **boot** vs **start**
- Use *start* and *restart* as much as possible to refer to starting a
computer on Tails; *boot* is almost always unecessary jargon.
- You might use *boot* when the word is displayed to the user by the
computer or when writing for a technical audience, like in our
design documentation.
- Use *boot* when referring to *boot options*, which are only
documented for workarounds or a technical audience.
- *For example*:
- Most computers do not start on Tails by default.
- The following instructions explain how to display the boot menu
and start on the USB stick.
- When starting Tails, add the <span class="command">toram</span>
boot option in the <span class="application">Boot Loader
Menu</span>. For detailed instructions, see the documentation on
[[using the <span class="application">Boot Loader
Menu</span>|doc/first_steps/startup_options#boot_loader_menu]].
- **bulleted lists**
Refer to this article from NN/g on [presenting bulleted
lists](https://www.nngroup.com/articles/presenting-bulleted-lists/).
Always add empty lines between list items to:
- Make them easier to read.
- Make them easier to translate. Each item from the list will be put
in a separate PO string in PO files by the PO plugin when building
the website.
- **Debian and Ubuntu versions**
Refer to Debian and Ubuntu versions primarily by their numbers, and additionally
by their codenames.
* *For example*:
- *For example*:
- Tails 3.0 is based on Debian 9 (Stretch)
- *Tails Installer* is available on Ubuntu 15.10 (Wily Werewolf) or later.
- **earlier** and **later**
Use to refer to versions of software.
Don't use *lower* and *higher* or *newer* and *older*.
Don't use "regular expressions" like *Tails 2.1.&#42;*.
- *For example:*
- If you are running macOS 10.10 (Yosemite) or earlier
- **future tense**
Whenever possible, use present, not future, tense. Don't switch
unnecessarily from present to future tense when present tense is
sufficient to express a sequence of steps or events.
Present tense is easier to read than past or future tense. Simple verbs
are easier to read and understand than complex verbs, such as verbs in
the progressive or perfect tense.
<a id="digit_grouping"></a>
- **digit grouping**
......@@ -21,7 +106,8 @@
Use a non-breaking thin space (HTML entity: `&#8239;`) or a space to separate
groups of three digits.
* *For example*:
- *For example*:
- $50&#8239;000
See [[!wikipedia Decimal_separator#Digit_grouping]] and [[!wikipedia
......@@ -40,23 +126,29 @@
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.
- *For example*:
- Install <span class="application">GNOME Disks</span> in Debian.
- **graphics card**
......@@ -64,6 +156,44 @@
And not *graphics adapters*, *graphics*, *graphical hardware*, or
*video card*.
- **media** and **installation media**
Use only in rare occasions where it is especially relevant to mention
both USB sticks and DVDs.
Tails is now primarily advertised for USB sticks. We prefer making our
text easy to read for the majority of people using USB sticks than to
be exhaustive and always mention DVDs, implicitly or explicitly.
- *For example*:
- Tails runs on a USB stick that you can plug in and use on almost
any computer.
- It is not possible to install Tails on a hard disk. Tails is
designed to be a live system running from a removable media: USB
stick or DVD.
- **network interface**, **Wi-Fi interface**
And not *card*, *device*, or *adapter*.
Still, **USB Wi-Fi adapters** are USB dongles that provide a Wi-Fi interface.
- **persistence feature**
To refer to the features available in the configuration of the
*persistent storage*.
- *For example*:
- [&hellip;] 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]]).
- **procedures** (a series of steps)
- Keep the number of steps low within a procedure (for example, below
......@@ -78,7 +208,7 @@
See also the *Microsoft Manual of Style: Procedures and technical
content*.
*For example*:
- *For example*:
<pre>
1. Make sure that you are connected to the Internet.
......@@ -88,23 +218,6 @@
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*.
Still, **USB Wi-Fi adapters** are USB dongles that provide a Wi-Fi interface.
- **persistence feature**
To refer to the features available in the configuration of the
*persistent storage*.
- *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]]).
- **Secure Boot**
Capitalize as a brand or feature. Writing *secure boot* would make it
......@@ -121,9 +234,36 @@
To refer to the kernel command line options that can be specified from
the *Boot Loader Menu*.
* *For example:* Adding `radeon.dpm=0` to the [[startup
options|/doc/first_steps/startup_options#boot_menu]].
- *For example:*
- Adding `radeon.dpm=0` to the [[startup
options|/doc/first_steps/startup_options#boot_menu]].
- **<span class="application">Tails Greeter</span>**
Without an article. Not *the Greeter*. Note the formatting as an application.
- **update** vs **upgrade**
- Use **upgrade** to refer to the replacement of a previous version of
Tails by another.
- *For example:*
- If you know someone you trust who already did the upgrade, you can
upgrade your Tails by cloning from their Tails.</p>
- You might use **update** to refer to other operations that update
some data or software outside of Tails releases.
- *For example:*
- Make sure to update your *dotfiles* each time you use the **init**
command of *keyringer*.
- The packages from your list of additional software will be updated
automatically when you connect to the Internet.
- **vulnerability** or **security vulnerability**
And not *hole* or *issue*.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment