How to create an effective README file for your charm

See also:

You’ve built your charm. This document guides you on how to start documenting it by creating an effective README file.

Your charm’s README file is likely to be the first encounter that people have with your charm. This document gives you a checklist of information to include in your README file so as to make it as useful and effective as possible.

The README file may include snippets from the underlying application documentation. However, the main focus should remain on the charm itself. In particular, you should make sure to include:

  • 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 in the Docs section of your charm’s page on Charmhub.

Last updated 2 years ago. Help improve this document in the forum.