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.

Contents:

Content

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.

Tooling

Platform.

This documentation is maintained through https://discourse.charmhub.io/ .

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 https://discourse.charmhub.io/. 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.

Contributions.

Pages can be edited or added by anyone with a Discourse account and a 3+ trust level on https://discourse.charmhub.io/.

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 https://juju.is/ docs, @tmihoc). Alternatively, for all https://juju.is/ docs, you can also file an issue on Issues · juju/docs · GitHub.

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

Formatting.

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).

Copyright © 2024 CC-BY-SA, Canonical Ltd

5 Likes

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.