How to contribute to MAAS documentation

Errors or typos? Topics missing? Hard to read? Let us know.

Welcome contributors! This guide provides step-by-step instructions to help you master the mechanics of MAAS documentation, so that you can contribute more easily.

Preparing

First, make sure your contribution is respectful, constructive. Don’t worry so much about the value or the technical correctness; our editors can deal with those as they come up. The most important thing is to get your thoughts down – and remember, if you’re not sure, you can use the survey form to share your ideas before changing a document.

At some point, you’ll want to familiarise yourself with the MAAS documentation style guide, linked above, but that is also something you can learn over time.

Edit documents

There are a few steps here; let’s take them one at a time:

  1. Locate the document you want to edit: Visit the MAAS documentation site and find the document you want to improve.
  2. Switch to the editable version: At the document’s footer, click on “Help improve this document.”
  3. Pop up the editor: Click the pencil icon below the title bar. A pop-up window will open.
  4. Start editing: Select “Edit Wiki” at the bottom right. An editor-preview split screen will appear.
  5. Make your changes: Make your changes in the left pane. The right pane will let you preview your changes, though you may have to scroll a little sometimes to see them.
  6. Save and submit: Click “Save Edit” to finalise. Updates may take up to 24 hours to appear on the main documentation site, so you might have to come back tomorrow to see your published changes.

Leave comments

Changing a published document is a big step. If you prefer, you can leave comments for our editors:

  1. Locate the document you want to edit: Visit the MAAS documentation site and find the document you want to improve.
  2. Switch to the editable version: At the document’s footer, click on “Help improve this document.”
  3. Pop up a comment box: At the end of the Discourse document, click “Reply.”
  4. Enter your comment: Enter your thoughts in the “Type here…” field.
  5. Post your comment: Click “Reply” to submit. Your comments will be reviewed by our editors. Almost any advice helps us improve.

Pro tips

  1. Keep it simple: Ensure your edits or comments are concise and to the point, but feel free to ask questions or note things you’re not sure about.
  2. Focus on helping: Focus on how your contribution can enhance the document’s clarity and usefulness.

Your contributions are valuable to the MAAS community. By following these guidelines, you can help make the MAAS documentation better.


Last updated 6 months ago.