charm-docs

name	charm-docs
description	Charm documentation conventions — README template, Charmhub description tabs, Diátaxis multi-page split, CONTRIBUTING
globs	["README.md","README","docs/**","CONTRIBUTING.md","CONTRIBUTING","HACKING.md","HACKING"]

Charm Documentation

These guidelines standardise documentation structure and content for Juju charms, covering the README file, Charmhub content, and the CONTRIBUTING file. They extend the general Canonical documentation standards. Based on Canonical spec DOC009.

Adapted from the charm-docs skill in tonyandrewmeyer/charming-with-claude, CC BY 4.0 (Tony Meyer, 2025). Reformatted for cantrip's bundled-skill frontmatter; content otherwise unchanged. See Provenance at the foot of this skill for the source link.

Documentation surfaces

A charm's documentation typically includes:

• README: description of the repository / project, stored with source code.
• Charmhub content: information published on charmhub.io (description, resources, integrations, libraries, configurations, actions tabs).
• Config files: serialised data for parsing (e.g. charmcraft.yaml).
• CONTRIBUTING file: guidance for building, testing, and contributing.

README

General guidance

• Give an overview of key aspects, but avoid multiple sources of truth — link instead of duplicating.
• Keep the README independent of Charmhub — equally useful offline, for unlisted charms, or older versions.
• Link to resources inside the repository where possible (e.g. charmcraft.yaml over Charmhub tabs).
• Keep the README up to date with charm code — incorporate into release checklists or CI checks.

README template

# <Charm name>
<!-- Badges -->

<!-- 1-2 sentence description.  Include the workload software
     and substrate (VM/K8s). -->

Like any Juju charm, this charm supports one-line deployment,
configuration, integration, scaling, and more.
For Charmed {Name}, this includes:
<!-- List or summary of app-specific features -->

For information about how to deploy, integrate, and manage
this charm, see the Official [<Charm name> Documentation](<link>).

## Get started
<!-- Brief summary of what the user will achieve. -->
<!-- Software and hardware prerequisites. -->

### (Optional) Set up
<!-- Environment setup steps (e.g. via Multipass).
     Link to Juju docs, noting only deviations. -->

### (Optional) Deploy
<!-- Deployment steps. -->

### Basic operations
<!-- Brief walkthrough of configurations, operations,
     or integrations (scaling, TLS, etc.) -->
<!-- (Optional) Link to charmcraft.yaml -->

## (Optional) Integrations
<!-- Required or highly recommended integrations.
     Link to Charmhub for the full list. -->

## Learn more
* <!-- Link to official documentation -->
* <!-- Link to developer documentation -->
* <!-- (Optional) Official webpage/blog -->
* <!-- (Optional) Troubleshooting/FAQ -->

## Project and community
* <!-- GitHub issues -->
* <!-- Launchpad (if applicable) -->
* <!-- Contribution guides -->
* <!-- Contact info, e.g. Matrix channel -->

## (Optional) Licensing and trademark

Charmhub content

Single-page description tab

Use when charm documentation lives elsewhere or is simple enough for one page.

Case 1 — external docs:

# <Charm name>

<!-- 1-2 sentence description with workload and substrate. -->

For information about how to deploy, integrate, and manage
this charm, see the Official [<Charm name> Documentation](<link>).

Case 2 — all docs on Charmhub:

Follow the same structure as the README, with adjustments:

• Add "documentation" to the title.
• No link to external docs.
• Point charmcraft.yaml references to Charmhub tabs instead.

Multi-page description tab (Diátaxis)

For charms with complex operations, structure documentation using Diátaxis (see References below):

• Index / Overview: landing page with standard home-page guidelines.
• Tutorial: end-to-end guided journey from setup to teardown. Every charm wrapping a standalone workload should have one, even if minimal.
• How-to: concise guides for specific goals (more practical than educational).
• Reference: release notes, lookup tables. Often minimal since configurations, libraries, and actions are already on Charmhub tabs.
• Explanation: reasoning, architecture, complex features — context and "why".

Each Diátaxis section with more than one page should have a dedicated landing page.

Not every category is always required — determine what is relevant and categorise accordingly.

Cross-referencing

• For all generic Juju behaviour, link to Juju docs rather than duplicating.
• Charm docs should focus on the charm-specific story: configs, integrations, and actions particular to the workload.
• Avoid trying to educate users about Juju in general.

CONTRIBUTING

Provide guidance for:

• Building the charm.
• Running tests.
• Contributing to source code and documentation.
• Any project-specific conventions.

References

• Diátaxis documentation framework: https://diataxis.fr/

Provenance

Adapted from the charm-docs skill in tonyandrewmeyer/charming-with-claude, CC BY 4.0 (Tony Meyer, 2025). Content reformatted for cantrip's bundled-skill frontmatter; otherwise unchanged.