Documentation guidelines for contributors

doc
#1

Juju documentation is maintained in the forum at discourse.charmhub.io. We welcome corrections and comments.

Each page in the documentation is a topic in the doc category of Discourse. Every docs page has a link to its corresponding topic. All you need to do is sign up on the forum.

You can comment on the topic, or if you have enough social credit on the site, you can edit most pages yourself. Finally, the sub-category doc-discuss is available for documentation related subjects.

Contents

Writing style

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. We’ve also supplemented that guide with some more Juju-specific details. 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:

Changes in behaviour between versions

Juju doesn’t change its defaults lightly. But it has happened. Use an admonishment to call this out, under the assumption that the reader of the body copy is using the most recent stable version of the client.

[note status="Using a version of Juju older than `v.2.3`?"]
In Juju 2.3, changed the `add-awesome` command to use `--full-throttle` by default.
[/note]

Using a version of Juju older than v.2.3?: In Juju v.2.3, changed the add-awesome command to use --full-throttle by default.

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 extra whitespace.

Emoji

Please do not use emoji in the documentation. They would be published on the web site and that’s not appropriate. :blush:

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

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)

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.

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>

Admonishments (also known as sidebars or boxed text)

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="important" status="Info"]
An informative note. This box is dark blue.
[/note]

This produces:

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

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

![description of image](<location>)

To resize images use the following syntax:

![Original|200x200](<location>)
![Percent|200x200, 50%](<location>)
![By Pixels|64x64](<location>)

For example:

image image image

These images are produced with the following:

![image|300x311](upload://xRC5B91fbxVhoUaFWQh4eQTZFfD.jpg) ![image|300x311,50%](upload://xRC5B91fbxVhoUaFWQh4eQTZFfD.jpg) ![image|100x104,50%](upload://xRC5B91fbxVhoUaFWQh4eQTZFfD.jpg)
5 Likes
Juju Documentation
#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: ?

1 Like
#3

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

1 Like
#4
#5

Thanks for alerting us to this problem. I’ve updated the CSS, so that they should be easier to distinguish

This is a note with type="negative".

This is a note with type="positive".

I will continue to refine this over time. Adding some distinctions that do not depend on colour, e.g. :warning:, :stop_sign:, :information_source:, would be very useful. I haven’t figured out how to do that in the CSS, as doesn’t understand :stop_sign:, for example.

[Edit: I’ve updated the CSS to use Unicode characters, rather than emoji images]

1 Like
#7

Am taking the opportunity to tighten up language, Juju docs need a bit of a cleanup.

#8
#9