How to document charms

The most successful charms are those with the best documentation. It is essential that as a charm developer you empower administrators, and other developers in the community, to understand the purpose of your charm, its behaviours, failure modes and ideal deployment conditions.

README

The README is likely to be the first encounter that people have with your charm. The README should be end-user oriented, focusing on what the charm does. While it may be prudent to include snippets from the underlying application documentation, the focus should be on your charm.

As a general rule, your README should provide

  • A quick getting started guide for a simple deployment
  • Mandatory configuration steps for minimal deployment - such as required relationships
  • Links to more detailed documentation (like a Discourse post - see below)
  • Where applicable, links to the OCI image source
  • Minimum requirements for a high availability deployment
  • Links to complementary/supplementary charms
  • Documentation for charm configuration options (if applicable)
  • Documentation for charm actions (if applicable)

Your README should not include developer-specific instructions. Please include any detailed information on how to build, test and contribute to your charm as part of the Discourse/Charmhub docs outlined in the next section.

Detailed documentation

Charmhub makes it easy to publish and collaborate on documentation for your charm. Documentation pages are managed in the Charmhub Discourse, which means community members can comment on them and help improve them directly. To get started documenting your charm, you must have already published your charm, and have a basic understanding of Markdown.

Each charm has its own “Docs” page at https://charmhub.io/<charm>/docs. The page structure allows for a navigation bar on the left hand side, with content displayed on the right. An example of this can be seen on the Mattermost charm page.

Getting started

To get started documenting your charm, first create a new topic in the ‘charm’ category. That link should set you up with a new topic and a basic template. Here are some guidelines:

  • Call your topic <charm name> docs - index
  • Tag your topic with the docs tag, and also with your charm name, for example: mattermost
  • The body of this topic should contain the cover page and navigation, including a full list of document pages for your charm
  • Each page of your documentation should be a new topic in Discourse

Below is a good cover page template that will help you setup your documentation with navigation and multiple pages (if you used the create topic link, this should be populated automatically):

The cover page of your docs. This should be some introductory text
which will be displayed on the front page of the Docs tab for your
charm. All the content above the 'Navigation' heading below is part
of the cover page.

# Navigation

| Level | Path     | Navlink                         |
| ----- | -------- | ------------------------------- |
| 1     |          | [Overview](/t/topic-title/<ID>) |
| 1     | install  | [install](/t/topic-title/<ID>)  |
| 2     | Subtopic | [Subtopic](/t/topic-title/<ID>) |
| 2     | Subtopic | [Subtopic](/t/topic-title/<ID>) |
| 1     | topic    | [install](/t/topic-title/<ID>)  |
| 2     | Subtopic | [Subtopic](/t/topic-title/<ID>) |

# Redirects

[details=Mapping table]
| Path | Location |
| ---- | -------- |
[/details]

Cover page

Please note that permissions to post links on Discourse are dictated by a trust level. You may need to interact with the forum before you can create your cover page with multiple links.

If you need help creating your cover page, please get in touch with us on the Community Mattermost

All of the text above your # Navigation header will appear on the cover page for your charm at https://charmhub.io/<charm>/docs. You can use Markdown formatting here, including headings, images, lists and code snippets. This is a good place to include the main usage of your charm and any limitations.

Navigation

The navigation section becomes essential as your documentation grows. To populate the navigation correctly, you must create a Markdown table with three columns, as shown below:

# Navigation

| Level | Path     | Navlink                         |
| ----- | -------- | ------------------------------- |
| 1     |          | [Overview](/t/topic-title/<ID>) |
| 1     | install  | [install](/t/topic-title/<ID>)  |
| 2     | Subtopic | [Subtopic](/t/topic-title/<ID>) |
| 2     | Subtopic | [Subtopic](/t/topic-title/<ID>) |
| 1     | topic    | [install](/t/topic-title/<ID>)  |
| 2     | Subtopic | [Subtopic](/t/topic-title/<ID>) |

The three columns are explained below:

Column Description
Level Used to create a tree structure in the navigation. Level 1 corresponds to a top-level item in the navigation
Path This value will be used to transform any Discourse URL to a path in your charm docs. For example: install creates a doc path at charmhub.io/<charm name>/docs/install
Navlink This column specifies the link to the Discourse topic. This should be specified as a Markdown link [text](link). An example Discourse topic link for this column is: [install](/t/install-the-best-charm/4563). Here, 4563 is the topic ID. This number uniquely identifies the Discourse topic, even if the title of the topic is changed at a later date.

Redirects

Redirects enable you to change the path to a specific doc at a later date should the need arise. Redirects are specified in a table, similar to the navigation section. The table must be in a section named Redirects. An example is shown below:

# Redirects

[details=Mapping table]
| Path | Location |
| -------------------------- | -------------------------- |
| <charm name>/docs/old-path | <charm name>/docs/new-path |
[/details]

When the above table is specified, anyone visiting charmhub.io/<charm name>/docs/old-path would be automatically redirected to charmhub.io/<charm name>/docs/new-path.

Adding pages

You can create as many documentation pages as you like for your charm. Each page just requires a new topic. Each new topic should have the tags doc and <charm name>. Don’t forget to update your documentation cover page with a link to the topic, and you may want to add the new topic to the navigation too.

You do not need to specify a navigation or redirect section in additional pages, these will be automatically handled by the documentation index topic.

Linking charms and docs

Once you have created your documentation pages, you need to tell Charmhub which index page to use for your charm. You can do this by updating your charm’s metadata.yaml, and then re-publishing it. The link belongs under the docs key in the metadata.yaml file like so:

# ...
docs: https://discourse.charmhub.io/t/<charm name>-docs-index/9999
# ...

Now build and publish your charm with charmcraft and your docs page should be live!

Documentation examples

A great example of some documentation maintained this way is the Snapcraft documentation. You can also see the corresponding Discourse post for inspiration.


Last updated a month ago.