Contributing to this documentation

This document contains information relevant if you wish to contribute to our docs – or are just curious to know how we do things and why.



Our documentation aims to be cooperative:

  • true
  • relevant
  • in the optimal amount
  • in the optimal form

at every level.

See more: Cooperative principle > Quality, Relation, Quantity, Manner

We believe significant improvements to truth, relevance, and optimal amount can be attained by improving form along the following lines:

  • Structuring all content into a Tutorial, How-to guides, Reference, and Explanation, according to Diataxis.

See more:

  • Structuring Reference content around basic tools (e.g., juju), entities (e.g., machine), concepts (e.g., high availability), and processes (e.g., bootstrapping), in alphabetical order, like a dictionary, with in-line links from one entry to another (example). Structuring the How-to guides into basic sets of recipes around a given entity (e.g., How to manage machines, with sections on Add, Remove, etc.), and using under-title “See also” links to link to the relevant entity (and concept) and back, and end-of-section “See more” links to link to the relevant tool(s) (and processes) (example) or to bridge to other immediately related how-to guides where relevant (example).

See more:

  • Following a coherent style consistently.

See more: Canonical Documentation Style Guide

:white_check_mark: Pro tip: The fastest way to catch up is to take a look at the published docs and how they are organised and written.



This documentation is maintained through .

On every page in the documentation, at the bottom of the page, there is a link “Help improve this document in the forum” that leads to its backing topic page on For the home page, the topic page is a page that contains a Navigation table where all the other pages are linked and a Redirects table for when the URL of a page changes.


Pages can be edited or added by anyone with a Discourse account and a 3+ trust level on

However, if your intervention is bigger than fixing a typo, it’s a good idea to comment on the page to discuss first.

You’ve commented on a doc but nobody has replied?

It helps to ping the author of the page or, where available, the responsible technical author (e.g., for all docs, @tmihoc). Alternatively, for all docs, you can also file an issue on

In either case, your name will be added to the Contributors list on the bottom of each doc.


Content is formatted in the usual way you would format a Discourse post.

See more: Discourse | Supported formatting in posts (markdown, BBCcode, and HTML (see esp. the link to markdown-it and CommonMark Spec)

Some tips and caveats:

  • headings: Start with level 2. (Level 1 is already used by document titles.)
  • emojis: Use sparsely – most would be the wrong style, and not all render nicely on the product website.
  • notes: Types are : information, caution, positive, negative.
  • images: You can drag and drop (though make sure to check how they render on the product website and adjust size if necessary).

:white_check_mark: Pro tip: The fastest way to catch up is to take a look at an existing doc (open it in Discourse, click on the pencil icon, then view its ‘Raw’ form).


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

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

1 Like

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

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