Canonical Documentation Style Guide
This is an as yet incomplete guide to the language and style conventions used for Canonical documentation projects. Topics are listed in the navigation to the left, and presented here as a single page to aid searching.
Diátaxis
Use Diátaxis to structure product documentation. Diátaxis provides rules that help you identify the type of document that you are writing. Document types include:
- Tutorial
- How-to guide
- Reference
- Explanation
Each type serves a different user need — it is useful to understand the needs being addressed as these will influence the documentation approach.
Refer to the official Diátaxis website for more information.
Spelling
Canonical is a UK based company, and uses British English throughout. There are many small differences between that and US English, but for the most part it comes down to spelling.
Some common differences are:
US English | UK English |
---|---|
license (verb) license (noun) | license (verb) licence (noun) |
defense (noun) | defence (noun) |
sausages, beans, and mash | sausages, beans and mash |
program (TV, agenda) program (IT) | programme (TV, agenda) program (IT) |
percent | per cent |
skeptical | sceptical |
catalog | catalogue |
traveling | travelling |
labeled | labelled |
-able | -eable |
-ize | -ise |
-or | -our |
In the most part this can be mitigated by simply enabling spell checking on your editing software and choosing an en-gb dictionary. The minor differences in grammar will (hopefully) be picked up in review by the documentation team.
Other common terms
We would like to standardise on the following spellings for common technology terms:
- online
- setup (noun), set up (verb)
- backup (noun), back up (verb)
- login (noun), log in (verb)
- web
- website
- internet
- systems management
- virtualisation
- space-separated, comma-delimited
- load balancer (only upper case as part of proper name e.g. Elastic Load Balancer)
Branding
Consistency in branding is important for a number of reasons, including the protection of trademarks where they apply. For our own products, and those of others we mention frequently, the following guidance applies.
Ubuntu
When we refer to Ubuntu |oǒ'boǒntoō|, we are usually referring to the distribution, rather than the Ubuntu project itself.
Our convention is to use the name, followed by the release number and, if applicable, 'LTS' to denote that the version is in Long Term Support. Optionally, you may also further identify the release by its codename (the first or both parts of the release name) if this is likely to be useful (e.g. some of our products also use the release names to identify versions).
Some examples of correct usage:
- Ubuntu 22.04 LTS
- Ubuntu 22.10
- Ubuntu 23.04 (Lunar Lobster) (note case!)
- Ubuntu 23.10 (Mantic)
- Ubuntu 24.04 LTS (Noble Numbat)
This also follows on to more specific products, e.g.
Ubuntu Server 22.04 LTS
In cases where the release may be mentioned many times in a single document, it is up to the author's judgement whether this could be reworded or replaced by simply 'Ubuntu' on subsequent mentions.
Note also that when referring to releases in the general sense, it is "an Ubuntu release".
Other Canonical products
Product | Notes |
---|---|
Anbox Cloud | |
Charmed Kubeflow | |
COS | Canonical Observability Stack |
Juju | |
Landscape | |
Launchpad | |
LXD | |
MAAS | Metal As A Service |
MicroCeph | |
MicroCloud | |
MicroK8s | |
MicroOVN | |
MicroStack | |
Mir | |
Multipass | |
Snapcraft | |
snapd | |
Ubuntu Core | |
Ubuntu Pro | |
Ubuntu Server |
Other commonly referenced products/projects
Product | Notes |
---|---|
NVIDIA | |
OpenStack | |
PostgreSQL | |
Kubernetes |
Contractions
Contractions are very common in spoken English and in many types of writing. Avoiding the use of them entirely makes it difficult to achieve a friendly, conversational tone. However, we should keep to contractions that are commonly understood and not part of some regional dialect, and only use them in "conversational" parts of the documentation (i.e. explanatory text).
Contractions you can use
contraction | meaning | notes |
---|---|---|
aren't | are not | |
can't | cannot | |
could've | could have | |
couldn't | could not | |
didn't | did not | |
doesn't | does not | |
don't | do not | |
hadn't | had not | |
hasn't | has not | |
haven't | have not | |
it's | it has / it is | |
isn't | is not | |
mustn't | must not | |
o'clock | of the clock | |
wasn't | was not | |
we'll | we will | |
we're | we are | |
we've | we have | |
won't | will not | |
would've | would have | |
wouldn't | would not | |
you'd | you had /you would | |
you'll | you shall /you will | |
you're | you are | |
you've | you have |
Don't use these!
contraction | meaning | notes |
---|---|---|
ain't | is not | colloquial - use isn't |
how'd | how did / how would | |
how'll | how will | |
I'd | I would | We don't use first person! |
'twas | it was | only relevant in Christmas fables |
something's | something is | avoid - confusion with possessive |
mayn't | may not | |
may've | may have | |
mightn't | might not | |
might've | might have | |
gonna | going to | |
gotta | got to |
Headings
Headings are important for navigation, for setting tone and for search indexing. Please bear in mind the following:
Sentence case
All headings and headlines should be sentence case. This means that you should only capitalise the first word unless it falls into one of the categories outlined below:
- product names
- personal names
- company names
- brands
- places
- Ubuntu Server, not Ubuntu server
Use: Do more with Ubuntu Don't use: Do More With Ubuntu
If it is not the actual product name, it should not be capitalised. Never capitalise keywords, technical terms and jargon.
Other considerations
- Avoid overusing punctuation in headings. Headings should not end with a period/full point/full stop
- Avoid links in headings
- Don't overuse
code
styling in headings - it can be useful to document command references, for example, but you should always consider if it is really needed - Imperatives should be used for 'How to...' style docs instead of gerunds (i.e. "Create an instance" rather than "Creating an instance")
- Do not skip levels of heading hierarchy (e.g. following an h1/# with an h3/###)
- Headings require content and should not be followed directly by a subheading
Dates
For consistency, we will use the following date format:
- Single day: 1 January 2013
- Date range within same month: 1-2 January 2013
- Date range across two or more months: 1 January - 2 February 2013
Numbers
Numbers in single figures should be spelled out in most cases. From 10 onwards, numbers should be written in digits.
Exceptions to this rule include numbered lists and units of measurement.
When writing out numbers over the 100s, remember to include commas.
Use: 7,000
Don't use: 7000
Code examples in documentation
DO NOT use prompt marks (e.g. $
or #
) in code samples. These cause problems
for users who sometimes mistakenly type them in, or who want to copy and paste
sections of code. They also encourage poor explanation of the code.
DO NOT use comments in normal bash code. E.g.:
juju deploy wordpress juju deploy ntp-master --to 2 #colocates with wordpress juju add-relation mysql wordpress
This may be a useful comment if you just have a bash script to communicate information, but we have words! It is clearer, more obvious and more helpful to simply explain, before after or during the code.
DO NOT use long blocks of code. Anything which doesn't comfortably fit on a screen is too long. Consider why you are showing it. Can it be broken up into parts? Long sections of code are rarely read in documentation. If the code is an example intended to be used rather than read, offer it as a download instead.
DO separate commands and output where appropriate. For example, instead of:
juju status environment: gce3 machines: "0": agent-state: started agent-version: 1.24.2 dns-name: 104.197.44.114 ... ...
It is more informative to break between the command and the output with explanation. This doesn't even have to be long. It breaks up the code blocks somewhat and makes the whole document more legible and less likely to cause unintended naps. For example
To check what is going on, run: juju status ... which should return some formatted information giving the current state of each unit and service: environment: gce3 machines: "0": agent-state: started agent-version: 1.24.2 ... ...
Placeholders in code blocks
There are many situations where it's necessary for users to provide their own information in a code block, such as IP addresses or names. It's common to substitute these values with a placeholder, consisting of terms within delimiters, representing the value to be replaced. For example:
lxc delete <instance_name>/<snapshot_name>
Here, the reader is expected to substitute their values for the placeholders. To minimise the risk of errors, instruct the reader that such values need to be substituted, especially when the first placeholder is referenced. There is no set style for the delimiter: the author should choose something unlikely to be confusing in the context, and use it consistently.
In longer code blocks the placeholders become more difficult to manage and easier to overlook. Instead, consider defining the placeholders as environmental variables. For example:
Define the channel for the charms required. For example, to select the stable release of 1.30: ``` CHANNEL=1.30/stable ``` Then proceed to fetch the required charms: ``` juju download easyrsa --channel=$CHANNEL juju download kubernetes-worker --channel=$CHANNEL ... ```
This approach has the following advantages:
- Separates user-supplied data from commands, making it easier to reference and explain
- Enables blocks of code to be copied without modification
- Reduces the chance of users making mistakes when editing the commands
Images
An image should not be overly cropped - allow for context.
DO NOT LINK IMAGES FROM A GOOGLE DRIVE This will work, until such a time as whoever owns the image closes their account (or leaves Canonical).
Video
Video is rarely an effective replacement for text in product documentation. The use of videos in documentation is generally not recommended, as they are:
- Challenging to do well
- Difficult to maintain
- Prone to accessibility issues
When there is a legitimate need for video content within documentation, a tool like asciinema is preferred. This generates text-based videos that are easier to maintain, while the text itself can be copied/pasted by the person reading the documentation.
Any videos which are included should meet the same standards of accuracy, clarity and quality expected of written documentation.
Words and phrases to avoid
Try to avoid jargon, long-winded phrases and words with negative connotations:
Avoid | Reason | Substitution examples |
---|---|---|
Allow | This suggests that we are in a position of power, permitting users or customers to conduct certain activities. | |
The ability to | Use We can instead of We have the ability to |
|
Is able to | Use Ubuntu can instead of Ubuntu is able to |
|
Not only...but also... | ||
Eliminate | Remove , destroy |
|
Execute | ||
Terminate | Stop , destroy |
|
Kill | Stop , destroy |
|
Disruptive | ||
Explosive | Major , significant , high impact |
|
Leverage | ||
Ecosystem | ||
Going forward | ||
In order to | To |
|
Form factor | ||
Use case | ||
End user | User |
|
Linux for human beings | ||
Thing | ||
Next level | ||
Harness |
It can be tempting to use flowery, official-sounding words rather than plain English. Try to keep it simple.
Latin words and phrases
Latinisms make documents less approachable to an international audience, and we can't assume our reader is familiar with them. They disregard the principle of plain English, and, worse, are often misunderstood or misused by both readers and writers.
Instead of reaching for a Latin phrase, choose among several English equivalents:
Instead of... | Use... |
---|---|
a priori | self-evident presupposed presumed assumed |
ad hoc | unscheduled unexpected improvised temporary bespoke |
ad infinitum | and so on to the fullest extent recursively |
cf. | refer to |
caveat | warning provision |
circa | around near |
de facto | current actual established |
ergo | therefore hence |
et cetera etc. &c |
and so on |
exempli gratia e.g. |
for example as an example such as |
gratis | free |
id est i.e. |
that is in other words |
nota bene n.b. |
note notice observe pay attention to keep your eye on |
in situ | in-place |
per diem | every day |
per capita | every/each person |
per se | necessarily intrinsically |
pro bono | freely given volunteered |
proviso | condition provided that |
stanza | division block paragraph |
status quo | state state of things |
verbatim | exact words exactly |
versus vs. |
compared to/with opposed to |
via | through with using |
vice versa | the reverse the other way around |
viz. | specifically namely |
The following Latin words and phrases are firmly embedded in everyday English, but you can still improve a document's readability by avoiding them:
Instead of... | Consider... |
---|---|
AM, PM a.m., p.m. |
Use 24-hour time. |
per | each every |
Lastly, these Latin words and phrases are widespread in academia and research. Their meanings don't belong in documentation:
- a postiori
- ad nauseum
- et al
- ibidum, ibid.
- sic
- stet
Admonitions
Admonitions (also referred to as "admonishments", "callouts" or "notifications") are a device used in documentation to draw attention to a particular statement or paragraph of text. Typically their use is to highlight:
- A consequence of performing a particular action
- An additional source of information which is useful but not required
- A helpful tip that will save effort/time
- A reminder of some pre-requisite or restriction
The Vanilla framework, which is used to publish most of our documentation, only allows for a particular set of pre-defined admonitions (or "Notifications" as they are referred to in that framework): Information and Warning.
Although other systems may allow for more scope it is advised to only use these two types, in the circumstances indicated below.
Warning
The Warning style of admonition is appropriate where certain actions or lack of action could have negative consequences - for example the loss of data or a service interruption.
Information
The Information admonition should be used for general notices which don't form part of the main narrative of the document, such as a useful shortcut, an additional source of information or a link to a related tutorial.
Note that the implementation of these admonitions relates solely to the colours and icons used with the notes. It is entirely possible to create an Information admonition and use the label 'Useful tip' or to call a Warning 'Danger of imminent death' to clarify the nature of the message.
Overuse of admonitions diminishes their impact and disrupts the reader's journey, so use them sparingly and try to avoid having several in quick succession.
Interacting with UI elements
Screenshots
Screenshots should be used sparingly.
A screenshot is not a replacement for clear descriptions in documentation. If an image is well described, a screenshot shouldn’t be necessary in many situations, and including many screenshots can clutter the documentation.
Screenshots also can’t be translated, so they aren’t as accessible to non-native English users or those using translated documentation. Additionally, those using screen-readers won’t be able to access the screenshots without alt-text.
Using UI elements as the English words
Don’t use UI elements as though they are English words.
For example:
- Use: When you’re finished, click Save to save your settings.
- Don’t use: When you’re finished, Save your settings.
Using the UI text as English words is less clear and may not transfer well to certain translated versions.
Click vs. Tap vs. Select
- Use “Click” for buttons that you click on (or “Tap” if the product is primarily for mobile devices)
- Use “Select” for selecting from multiple options (e.g., a dropdown menu, multiple menu items, etc.)
- Use “Select” when there are multiple instructions separated by > (e.g., Select Preferences > Languages)
For example:
- Use: Click Settings to open your user settings.
- Use: Select the machines you want to register, then click Save.
- Use: Tap the application to open it.
- Don’t use: Select Add bookmark to save your bookmark.
“Click”/”Tap” is preferred over “Select” for UI elements that are definitive. This is because “Select” has an open-ended connotation, while “Click”/”Tap” is direct and definitive. Although “Click”/”Tap” may technically be wrong in certain situations (e.g., if a user is using the mobile version of a web page on their desktop computer), it’s important to consider accessibility and the primary audience of the documentation over these edge cases. Differentiating when users may have to select from options or select more than one option can be useful for them, especially when following a longer how-to guide (e.g., Click X, Click Y, Click Z, Select the settings you want to apply, Click Save). This extra level of precision can also be helpful for non-native English users and those using translated documentation.
Bold vs. Italics
Use bold for UI elements the user clicks/selects, and quotes or quotes with italics when drawing attention to a specific word or phrase, or using the name of a word as a word.
For example:
- Use: Click Save
- Use: In the Computers column, click Register a new computer.
- Use: Click the link in the text “You can register new computers by following these instructions”.
- Use: Use the word “and” instead of “or”.
- Use: Use the word “and” instead of “or”.
- Don’t use: Once you’ve made your selections, click Save.
Bolding UI elements can help make the documentation easier to scan for critical information. This is especially good for users who aren’t reading the documentation for the first time and just want key information without having to sift through extraneous documentation.
Angled brackets
You can use a right angled bracket > for navigating menu items with multiple steps.
For example:
- Use: Select Preferences > Languages > English
- Use: You can navigate to File > Documents and select one of your saved documents.
- Use: Select Blank Document from the File > New menu.
- Don’t use: Navigate to the home page > Click Packages > Select each package you want to export > Click Export
Using the right angled bracket (>) is at the author’s discretion; however, you’re encouraged to use this format where possible to keep things concise.
Checkboxes
Use “Select” and ”Clear” or “Check” and ”Uncheck” together at the author’s discretion, depending on what is most natural in context.
For example:
- Use: Select the Enable firewall checkbox.
- Use: Clear the Add bookmark checkbox.
- Use: “Check the computer(s) you want to register” with “Uncheck any computer(s) you don’t want registered”
- Don’t use: Check the computer(s) you want to register, or clear any computer(s) you don’t want registered
This helps establish consistency in how we refer to checkboxes in the UI.
Keyboard shortcuts and keyboard keys
Use “Press” when instructing the user to use a specific keyboard shortcut or keyboard key, and “Use” when instructing them to use collective or ambiguous keys.
For example:
- Use: Press
Ctrl + C
- Use: “To save, press
Enter
.” or “To save, press theEnter
key”. - Use: Use the arrow keys to navigate the menu.
- Don’t use: Click the
Enter
key.
This ensures they don’t get confused with our use of “Click”/”Tap”/”Select”.
“Icon” vs. “Button”
“Icon” is for a symbol/image that represents an object or function, and “button” is for UI elements that initiate action when clicked. Icons typically don’t include explanatory text, and are sometimes buttons or included on a button.
If using the image of an icon or button, write the name of the icon/button directly after it or add alt-text. Avoid using the terms “icon” or “button” unless they’re needed for clarity.
For example:
-
A search icon (also may be a button):
-
A save button:
-
A reply button with an icon:
-
Use: Click for more options. (Alt-text: “the menu”)
-
Use: Click the star to add the page to your favorites.
-
Don’t use: Click the pencil icon to edit the post.
Hyperlinks
Here are some pointers about the general use of hyperlinks and how to format them correctly.
General use
Avoid excessive links in the same paragraph or instruction. If you find yourself introducing several links in your content, consider listing them in a separate section called "Related topics", "Additional resources", or similar.
When linking to versioned files or specific lines of code, copy the permalink instead of the URL if available. This will ensure the link is bound to the current revision of the file, so it will direct to the same content even if the file changes.
Formatting
Try to make the link text match the title or heading that you are referencing. Make sure either the link text itself or the surrounding sentence provides enough context about the contents of the linked section.
Avoid phrases like "this document", "this article", or "click here" as the link text.
For example, when referring to a section called "Formatting":
- Use:
See the [formatting guidelines](#formatting) for hyperlinks.
- Use:
See the [Formatting section](#formatting) for guidelines about hyperlink formatting.
- Avoid:
See [Formatting](#formatting).
- Avoid:
See [this section](#formatting).
Avoid using a URL as the linked text.
- Use:
[Page title](https://page-url.com)
- Avoid:
[https://page-url.com](https://page-url.com)
Avoid superfluous links to external pages that could become outdated or deprecated. External links such as the documentation's upstream project or repository are fine.
Inform the user the link is external to the current doc set by specifying the source.
- Use:
To submit an issue related to the code, see the [Contributing guide](www.github.com/org/repo/contributing.md) on GitHub.
- Avoid:
For more information, see [How to format hyperlinks](www.external-style-guide.com/hyperlinks)
If clicking the link performs an action, like downloading a file, link the entire action in the sentence.
- Use:
First, [download
file.zip](file.zip)
- Avoid:
First, download the [file](file.zip)
FAQs
There are some grammatical issues that can cause confusion. Here are some of the main offenders.
What is the difference between fewer and less?
Fewer means “not as many,” less means “not as much.”
A commonly-quoted example used to highlight the distinction is: “There are fewer cars on the road, which means there is less traffic.”
Also compare: “The fewer people know about this the better” and “The less people know about this the better”.
Note: The rule does not work if the number is counted as a quantity or as a unit. For example: “She paid less than ten pounds for it” or “His last jump was less than fifteen feet”.
What is the difference between that and which?
This can, and has, caused many arguments, so it's probably best not to get too worried about it. A useful guide is: that defines, which informs.
This is not a cast-iron rule but it can help: “This is the house that Jack built, but I think the one next door, which Jack also built, is more attractive.”
“Which” is often clausal, so is predominantly preceded by a comma - compare “The police stopped the second car that was driven by a woman.” and “The police stopped the second car, which was driven by a woman.”
Is it OK to split an infinitive?
There is no grammatical rule that says you can't split an infinitive. Sometimes, it is definitely better to split:
"Can dot.com companies ever hope to fully recover their share values?"
This sounds much better than moving “fully” in front of “to recover” or behind it. The key is not to write anything that is ambiguous or inelegant.