Ubuntu Core documentation guidelines
Our documentation is a community effort, published via the Discourse forum hosted at discourse.ubuntu.com. We warmly welcome community contributions, suggestions, fixes and constructive feedback.
New Discourse users are temporarily limited in their capabilities (called their trust level) until they’ve read and participated a little in the forum. At Trust Level 1, they can create and edit documentation freely.
Feel free to modify any documentation topic with updated or more insightful information. If you already participate in the Ubuntu Core community, you don’t need additional permissions; pages are freely editable within the forum itself. Of course, feel free to ask and discuss when appropriate.
Documentation consistency is vital, which is why we’re listing some guidelines below, but don’t let this formality put you off - just start writing and editing. If something is inconsistent, we’ll fix it.
As Voltaire wrote, “Perfect is the enemy of good,” and we’d rather have documentation we can fix than non-existent documentation we can’t.
Style and language
One of our biggest challenges is accommodating an audience with a huge variation in experience, from beginners exploring the Ubuntu Core on their Raspberry Pi, through device creators experimenting with gadget snaps, to experts harnessing the API and deploying their apps to thousands of IoT devices.
Consequently, we try to:
- pitch the writing and editing appropriately for the subject
- write inclusively and assume very little prior knowledge of the reader
- link or explain phrases, acronyms and concepts that may be unfamiliar, and if unsure, err on the side of caution
Some general tips:
- use a spell checker
- resist being overly formal
- resist being overly verbose
- verify links and examples
We (mostly) adhere to the Ubuntu style guide. In particular:
- we use British English (en-GB), for example:
- the ise suffix in preference to ize (capitalise rather than capitalize)
- our instead of or (as in colour and color)
- license as a verb, licence as a noun
- catalogue rather than catalog
- dates take the format 1 January 2013, 1-2 January 2013 and 1 January - 2 February 2013
Discourse Markdown
Documentation is written in the Markdown format supported by Discourse.
Mostly, you don’t need to worry about the syntax. You can simply use the style toolbar in the Discourse topic editing window to mark the elements you need.
Headings and titles
## Subheading within a document
### Subheading of a subheading
Each page of documentation requires a top-level heading (# Heading
). This is used to create the page title in the documentation. It can be different to the post title.
Headings and subheadings need to use sentence case, which means the first letter is typically the only one capitalised, unless the title includes names, product names or acronyms.
Lists
For a bullet list, use the following syntax:
We (mostly) adhere to the Ubuntu style guide, for example:
- we use British English (en-GB):
- the _ise_ suffix in preference to _ize_
And for a numbered list, precede each item with 1.
(the numbering then becomes automatic, and it’s easier to insert new items):
1. This is the first item
1. This is the second
1. This is the third
1. This is a sublist
Unless a list item is particularly long (which should be avoided) and includes punctuation, don’t end the item with a full stop. If one item needs a full stop, add the full stop to other items too.
Code blocks
Enclose a code block with three backticks and include the type of code:
```yaml
name: gimp
version: '2.10.8'
summary: GNU Image Manipulation Program
```
The most common code types are: bash
, yaml
, json
, and no-highlight
. The last is like a miscellaneous type. It is often used to display command output.
Also, a little contentiously as it goes against the style guide, we use a command line dollar prompt ($
) to demarcate input and output in the same code block:
$ snap version
snap 2.36.1
snapd 2.36.1
series 16
ubuntu 18.04
kernel 4.15.0-39-generic
In sympathy with the command line, we replace $ with # when running commands from root.
Inline code
Use a backtick to mark inline commands and other literals. For instance, to create $SNAP_DATA
:
For instance, to create `$SNAP_DATA`:
Hyperlinks
For links to internal files or external URLs, use the following format:
[visible text](url)
The visible text
is what will appear in the documentation. The url
is either the full URL of a link outside of the documentation, or the topic reference without the domain name for a page within the documentation.
To link to https://forum.snapcraft.io/t/snapcraft-overview/8940
, for example, you would use the following:
For more details, see [Snapcraft overview](/t/snapcraft-overview/8940).
The Discourse topic identifier, 8940 in the above example, is optional and can be omitted.
Anchors
Discourse Markdown does not support anchor links to a position within the same page or another document.
However, you can use standard HTML within Markdown, which means we can manually add HTML anchor elements that can be linked to.
The recommended way to create anchors is using heading elements with an ID. The ID needs to have heading--
as a prefix:
<h3 id='heading--myanchor'>Link to me</h3>
To create an anchor called base-snap
, for example, enter the following into your document:
<h3 id='heading--base-snap'>Base snaps</h3>
This can now be linked to with the following:
/t/snapcraft-overview#base-snap
Use HTML sparingly as it can make the raw text difficult to read.
Notes and admonishments
Admonishments in Discourse use BBtext markup syntax. Using [note]
… [/note]
draws a box around the contained text.
[note type="important" status="Info"]
An informative note. This box is dark blue.
[/note]
This produces:
An informative note.
You can omit the status header.
[note type="important"]
A note without a title.
[/note]
And its output:
A note without a title.
The type
parameter is optional, but recommended:
[note]
A note that only uses default settings.
[/note]
And its output:
A note that only uses default settings.
Types of [note]
Changing the type
parameter changes how it is presented to the reader:
-
important
(default) caution
positive
negative
The below examples are produced using type and status combinations of ‘caution/Warning’, ‘positive/High score’, and ‘negative/Game over’, respectively:
Here be dragons.
Uses caution
type.
Great work.
Uses positive
type.
Please try again.
Uses negative
type.
Hyperlinks cannot be word-wrapped within admonishments. Doing so will not format the links.
Comments
Sometimes it’s useful to provide information to documentation editors. For that, add the comment inside a block quote that includes the icon. These will be excluded from the dedicated documentation web site, but will be visible in the forum when editing. It may look similar to this:
[quote]
:construction: **NOTE TO EDITORS** :construction:
This note is not visible in the dedicated documentation site.
[/quote]
Foldouts
When a page contains a lot of extraneous information such as walkthroughs or reference tables, a foldout can be used. This will create a collapsed header which, when clicked, will expand to display all the content below it.
Foldout syntax in Discourse uses two sets of square brackets with an open and close details tag that acts as the title in the opening brackets:
[details=Manually create a network on a 10.x.x.x subnet]
If you try to run `lxd init` on a system that is connected to a network with a `10.x.x.x` subnet,
then the final step of the Iinit* may fail with the following error:
[/details]
The above will appear as follows:
Manually create a network on a 10.x.x.x subnet
If you try to run lxd init
on a system that is connected to a network with a
10.x.x.x
subnet, then the final step of the Iinit* may fail with the following error:
Images
Most of our documentation covers command line tools, editing and developing. However, if relevant, we highly encourage the use of images. An image should be easier to understand than text, reinforce concepts being discussed in the topic, and break the monotony of words following words.
When making images:
- do not crop your images too closely to allow context
- use a resolution high enough to make text legible and work with high-DPI displays
- a wide aspect ratio fits better with the width of the rendered documentation
- save with lossless compression, such as PNG for screenshots (JPG is acceptable for photos)
Images can be simply dragged and dropped into the topic you’re editing, or uploaded via the toolbar icon. It can also be helpful to edit the description field of an image link after uploading:
