Our documentation is a community effort, published via the DIscourse forum hosted at discourse.ubuntu.com. We welcome corrections and enhancements as well as suggestions and constructive criticism.
You can modify (almost) any page by visiting the Discourse Documentation category, where each documentation web page corresponds to a Discourse topic. In addition, every web page has a link that leads directly to its corresponding topic. All you need to do is sign up on the forum.
If you’re unsure of your intended contribution you can leave a post on the topic in question asking for guidance. Finally, the Documentation-discuss Ceph sub-category is available for documentation related subjects.
Contents
Writing style
Documentation consistency in terms of writing style is vital for a good user experience.
Here are some general tips:
- define acronyms and concepts–don’t assume others are familiar with the subject
- use a spell checker
- resist being overly formal
- resist being overly verbose
- verify links and examples
- don’t repeat what’s been covered in other posts - use hyperlinks
We adhere to the Canonical Documentation 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
Line length
Discourse honours the line length in its editor. Therefore, ensure that a paragraph does not take on a jagged appearance (long lines mixed with short lines). Use common sense when inserting line breaks so the resulting text “looks good” to the reader.
Emoji
Please do not use emoji in the documentation. They would be published on the web site and that’s not appropriate. 
Source format
Documentation is written in the CommonMark 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.
Pro tip:
If you can’t get the results you want try to find a similar post and use the following URL format to view its raw markdown https://forum.example.com/raw/{topic-id}/{post-id}. See the current post for an example.
Individual elements are now explained. Some formatting can be achieved in more than one way. Kindly use the methods described in order to maintain consistency throughout the documentation.
Headings and titles
## Subheading within a document
### Subheading of a subheading
We don’t use the top-level heading (# Heading) as the topic title serves this purpose.
Headings and subheadings should use sentence case, which means the first letter is the only one capitalised. Proper nouns and acronyms are exceptions.
Lists
For a bullet list, use a hyphen ( - ). Sub-lists will use an hyphen indented at least 2 spaces:
We (mostly) adhere to the Ubuntu style guide, for example:
- we use British English (en-GB):
- the _ise_ suffix in preference to _ize_
For a numbered list, use 1. to precede each item. The numbering will be rendered automatically. One benefit is that it’s simple to insert new items:
1. This is the first item
1. This is the second
1. This is the third
1. This is a sub-list
The indent here needs to be at least 3 spaces.
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 one to all the items.
Tables
An example table:
| heading 1 | heading 2 | heading 3 |
|---|---|---|
| cloud | user | pass |
| type | access | key |
It is produced by the following markdown:
heading 1 | heading 2 | heading 3
-|-|-
cloud | user | pass
type | access | key
Use colons for horizontal alignment:
| heading 1 | heading 2 | heading 3 |
|---|---|---|
| left | centered | right |
| type | access | key |
The markdown:
heading 1 | heading 2 | heading 3
:-|:-:|-:
left | centered | right
type | access | key
Left-aligned is the default, and does not need to be stated.
The number of dashes has no effect on the final result.
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 text. The last is like a miscellaneous type. It is often used to display command output and does not highlight anything.
Note:
The text type is usually the best choice as the other types often appear to highlight things randomly from the reader’s perspective.
Do separate command input blocks from command output blocks. For input, do not use a command line prompt (e.g. $ or #) and precede the output block with some kind of intelligent message:
lsb_release -r
Sample output:
Release: 18.04
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)
For internal pages the full URL is not necessary. The below forms will also work for, say, https://discourse.jujucharms.com/t/clouds/1100:
[Clouds](/t/clouds/1100)
For linking to headers (see next section ‘Anchors’), this can be used:
[Adding clouds](/t/clouds/1100#heading--adding-clouds)
Or, if within the same page:
[Adding clouds](#heading--adding-clouds)
Anchors
To link to a header within the same page or in another page you will need to use HTML tags. Importantly, this will also create header links on the published page so that they can be used universally on the internet.
For example, to create a link to the (second-level) destination header of “Adding clouds” edit the header on the destination page (clouds here) so it changes from this:
## Adding clouds
to this:
<a href="#heading--adding-clouds"><h2 id="heading--adding-clouds">Adding clouds</h2></a>
As shown above, base the anchor name (heading--adding-clouds) on the destination header (Adding clouds), even if this is not strictly required. This is for consistency and logic.
Within the same Discourse instance, this can now be linked to with the following URL:
/t/clouds/1100#heading--adding-clouds
Or, if within the same page:
#heading--adding-clouds
External to the Discourse instance (on the internet), a full URL will be needed but with the #heading--adding-clouds portion affixed to the end.
Warning: Avoid altering the names of existing anchors as doing so may break existing links to it. It is not obvious what other pages are linking to it.
Admonishments
To highlight something, you can use admonishment. Admonishments are self-contained snippets that are not part of the main flow of the document. They’re also used as sidebars in printed works. The wording is correct if the admonishment can be understood independently of the body copy and removing it does not impact readers’ understanding of the surrounding text.
Syntax for admonishments
Admonishments in Discourse use BBtext markup syntax. Using [note] … [/note] draws a box around the contained text.
[note type="note" status="Note"]
An informative note. This box is dark blue.
[/note]
This produces:
Note: 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:
note-
important(default) cautionpositivenegative
The below examples are produced using type and status combinations of ‘caution/Warning’, ‘positive/High score’, and ‘negative/Game over’, respectively:
Warning:
Here be dragons.
Uses caution type.
High score:
Great work.
Uses positive type.
Game over:
Please try again.
Uses negative type.
Hyperlinks cannot be word-wrapped within admonishments. Doing so will not format the links.
Comments
Here we’ll explain two ways to leave comments in a page. Doing either will prevent the text from being published on the documentation web site.
Firstly, there may be times when a little explanation (to other editors) is required amidst a page. Use standard HTML comment tags:
<!--
The reason for doing it this way was due to blah blah blah.
-->
Secondly, intended work may get left undone or there may be external circumstances that affect the documentation (e.g. software bugs). These things should also be noted for future editors. Use a TODO list for this within a comment at the very top of a document:
<!--
TODO:
- Critical: general review required
- Ubuntu codenames hardcoded. Remove Trusty when EOL
- Bug tracking: https://bugs.launchpad.net/juju/+bug/1797399
-->
Foldouts
When a page contains a lot of extraneous information, such as software code or file contents, a foldout can be used. This will create a collapsed header, which, when clicked, will expand to display all the content below it.
[details=This is the visible header]
This text is completely hidden.
The reader clicks the header to reveal its contents.
[/details]
The above will produce:
This is the visible header
This text is completely hidden.
The reader clicks the header to reveal its contents.
Images
An image should be easier to understand than text, reinforce concepts being discussed in the topic, and break the monotony of a long stream of paragraphs.
When making images:
- do not crop your images too aggressively; add a little extra to provide 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 edit field, or uploaded (local device or a public URL) via the toolbar icon. It can be helpful to edit the description field of an image link after uploading:
To resize images based on pixels or a percentage of pixels use the following syntax:
![description of image]|200x200](<location>)
![description of image]|200x200,50%](<location>)
![description of image]|64x64](<location>)
For example:
These images are produced with the following:
