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](#heading--content)
- [Tooling](#heading--tooling)


<a href="#heading--content"><h2 id="heading--content">Content</h2></a>

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](https://en.wikipedia.org/wiki/Cooperative_principle)

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: 
> - [Ubuntu Blog | Diátaxis, a new foundation for Canonical documentation](https://ubuntu.com/blog/diataxis-a-new-foundation-for-canonical-documentation)
> - [Diataxis](https://diataxis.fr/) 

- 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](https://juju.is/docs/juju/action)).  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](https://juju.is/docs/juju/manage-actions)) or to bridge to other immediately related how-to guides where relevant ([example](https://juju.is/docs/juju/manage-applications#heading--scale-an-application-vertically)).

> See more:  
> - [The pragmatic programmer > Topic 10: Orthogonality](https://learning.oreilly.com/library/view/the-pragmatic-programmer/9780135956977/f_0028.xhtml#orthogonality)
> - [Code complete > Chapter 6: Working classes](https://learning.oreilly.com/library/view/code-complete-2nd/0735619670/ch06.html)
> - [Code complete > Chapter 7: High-quality routines > Operations that seem too simple to put into routines](https://learning.oreilly.com/library/view/code-complete-2nd/0735619670/ch07.html#:-:text=Operations%20That%20Seem%20Too%20Simple%20to%20Put%20Into%20Routines)

- Following a coherent style consistently.

> See more: [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en?_ga=2.155126013.436828396.1711530350-1435524421.1686558765)

[note type=positive]
: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. 
[/note]


<a href="#heading--tooling"><h2 id="heading--tooling">Tooling</h2></a>

**Platform.**
<!--
[note type=information]
A small number of Reference docs are generated automatically from the code. The Discourse versions of these documents are tagged `autogenerated` ([example](https://discourse.charmhub.io/t/list-of-controller-configuration-keys/7059)). The way to edit these docs is to submit a pull request against the source code linked to at the top of the page on GitHub.
[/note]
-->
<!--
Both https://juju.is/ and  https://charmhub.io/ documentation 
-->
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/.

[note type=information]
- 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. 

[/note]

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

[note type=positive]
**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.
[/note]

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](https://meta.discourse.org/t/supported-formatting-in-posts-markdown-bbcode-and-html/239348) (see esp. the link to [`markdown-it`](https://markdown-it.github.io/) and [CommonMark Spec](https://spec.commonmark.org/))

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

[note type=positive]
: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). 
[/note]