Documentation guidelines


#1

Our documentation is a community effort, published via the DIscourse forum hosted at discourse.jujucharms.com. We welcome corrections and enhancements as well as suggestions and constructive criticism.

You can modify (almost) any page by visiting the Discourse Docs 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 sub-category Docs-discuss 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

Versioning

There are no distinct versions of the documentation that correspond to Juju software versions. Instead, a single pool of documentation pages is used to cover all software versions. This means that when a new feature is documented it must be communicated to the reader what Juju version it applies to.

Associating a feature to a Juju version is done by formatting the version in this way (for 2.5.0):

v.2.5.0

Examples:

In v.2.5.0, charms are allowed to include a LXD profile.

As for the bootstrap command, the --to option is limited to either pointing to a MAAS node
or, starting in v.2.5.0, to a LXD cluster node.

Kubernetes charms (v.2.5.0) can be deployed when the backing cloud is a Kubernetes cluster.

Here is a list of advanced LXD features supported by Juju that are explained elsewhere:

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.

Note that the web site will continue to respect the extra whitespace.

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 (headings in particular). 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.

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`:

For links to internal files or external URLs, use the following format:

[visible text](url)

To make things crisper and more legible you can also use an intermediary label and then associated that label with the actual URL (usually at the bottom of the document):

[visible text][label]
.
.
.
[label]: url

The visible text is what will appear in the documentation.

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)

Or just:

[Clouds](/t/clouds)

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.

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:

<h2 id='heading--adding-clouds'>Adding clouds</h2>

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.

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

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 admonishments. This draws a box around some text. An admonishment should be viewed as drop-in blob of information that can later be removed without causing a need to rearrange the surrounding text. Use this element judiciously.

[note type="important" status="Note"]
An informative note. This box is dark blue.
[/note]

This gives:

Note: An informative note. This box is dark blue.

You can omit the status header:

An informative note devoid of a title. This box is dark blue.

The below examples are produced using type and status combinations of ‘caution/Warning’, ‘positive/High score’, and ‘negative/Game over’, respectively:

Warning: A warning note. This box is yellow.

High score: A positive note that should include a title. This box is green.

Game over: A negative note that should include a title. This box is red.

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
 - This text is not visible on the doc web site but it is within Discourse.
-->

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

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 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 via the toolbar icon. It can be helpful to edit the description field of an image link after uploading:

![description of image](url)

Documentation migrated to Discourse
#2

Just a quick note, I’m colourblind and I see almost no difference between the different admonishment boxes. A 1 pixel border is just too thin for me to make out any colour. Maybe it’s best to give them a different background too, or use emoji like :warning: ?


#3

Thank you for mentioning this. I will definitely consider this.