Updating Documentation

Everyone in the Juju team is responsible for keeping its documentation up-to-date.

Workflow 1: Pull Request

This workflow has the advantage that you’re not responsible for checking for stylistic consistency.

The discourse branch of the github.com/juju/docs repository contains a copy of all of the topics within the #docs category.

To maintain consistency, please ask the documentation lead for a review before merging PRs.

Action Command
Clone the repository git clone git@github.com:juju/docs.git
Switch to the discourse branch git checkout discourse
Create a feature branch git checkout -b fix-relations-typo
Edit the docs
Push to GH
Create a PR https://github.com/juju/docs/compare/discourse...fix-relations-typo?expand=1
Request a review

You don’t necessarily need to work within your own fork of the project.

Workflow 2: Edit in place

Editing docs within Discourse will immediately update what is presented to users within our docs page.

If you want to do substantial edits this way, then create a duplicate of the current page and work on that. That will enable you to save work in progress without impacting what users see. Once you’re finished, copy and paste your new content into the original page. Then archive the topic that you used for your draft.


Syntax highlighting/linting
Discourse does not use valid Markdown. It also supports BBcode, for example. Your editor (probably) won’t have a syntax extension that supports it. C’est la vie.

New pages
Use the + New Topic button in the web UI to create a new page.

Images and videos are difficult to manage via the Discli/GitHub flow. You’re recommended to upload content via the Upload button within Discourse’s web UI then refer to that URL.


  • The content that’s available on juju.is/docs is rendered on-the-fly from the Markdown-ish sitting in Discourse.
  • discli is a tool for helping work locally with topics inside Discourse