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
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/.
-
To edit a doc: Click on its pencil icon.
-
To add a doc: On https://discourse.charmhub.io/, click + New Topic, add a suitable category + tag (for https://juju.is/ docs:
doc+juju|sdk|dev; for https://charmhub.io/ docs:charm+<the conventional tag for a given charm / bundle>) edit the doc, then link it in the Navigation.
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 https://github.com/juju/docs/issues.
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-itand 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).
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).
?
, 
, would be very useful. I haven’t figured out how to do that in the CSS, as doesn’t understand