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.
Quirks
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.
Multimedia
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.
Background
- 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