Editing MAAS documentation

Overview

Duration: 2:00

MAAS documentation is open-source, so everyone is welcome to contribute. Access is controlled via permissions, with changes vetted (and possibly edited) by anyone else with editing rights. The RAD (Reader Adaptive Documentation) format used by MAAS is no more difficult than a very simple programming language, and provides a great deal of flexibility. This tutorial will explain how to make basic contributions and corrections to this documentation set.

In this tutorial, you will learn:

  • Where to find MAAS documentation
  • How MAAS articles are structured
  • How to find specific MAAS articles
  • How to verify that changes are needed
  • How to request edit permission for the documentation set
  • How to do basic editing and save your work
  • How to use discourse markdown to format ideas
  • How to work with RAD selectors and sections

What you’ll need

How you’ll interact

  • In each section, there is at least one “Try it!” heading
  • Under those headings, you’ll find instructions and clickable images
  • Clicking the images will bring you to a short, example video loop
  • Copy the actions in the video to try some actions “hands on”

Should i edit this document?

Duration: 1:00

Before making changes to a MAAS document, you must consider the following:

  • Will your contribution improve the conversation or enhance the relevant knowledge of the document in some way? It’s important for you to know whether you’re really contributing something, or just changing to suit your personal style or wording preferences. When you’re not sure, you generally shouldn’t change the document yet.

  • Is your contribution free of editorial commentary, especially about other people or groups? If you have a bias that isn’t related to the factual information in the document, it’s probably a good idea to root that out before changing it.

  • Are you certain of the technical accuracy of your contribution? If not, it’s better to wait until you can verify any uncertainties, rather than lead people astray.

Finding the discourse document

Duration: 4:00

So you’ve noticed something about a document that you know should be corrected, and you’ve decided that your information and expertise will be helpful. Now what?

The next step is to begin editing the document. There is more than one way to handle the editing – as you’ll see later – but for now, you can go ahead and locate the discourse document that corresponds to the maas.io/docs article you want to change. Luckily, it’s very simple:

  1. Locate the floating link at the bottom of the relevant article, the one that says “Help improve this document in the forum.”

  2. Click the link to go to the discourse article.

Let’s give this a try right now. Find a new tab in your browser, enter “maas.io/docs” in the address bar, and hit , like this:

emd-1

The MAAS documentation index page should come up in the browser. Add sample-document to the end of the URL in the address bar, and hit again:

emd-2

Now find the floating link at the bottom of the article, like this:

emd-3

This should bring you to a somewhat different version of the document, once which is a little less “fancy.” This is the discourse article from which the maas.io document is generated. If you look at the browser address bar on a maas.io document, you’ll see an address which makes sense for an external user.

For example, if you consider the page https://maas.io/docs/sample, it has a URL structure which makes the purpose of the document plain:

[insert picture here]

If you click on the “Help improve this document in the forum” link, you’ll see a different address in the browser address bar: [insert address here]:

Click on the topic title once, to clear the HTML query from the URL. The number at the end of the remaining URL is the discourse topic number, which is how discourse actually keeps track of documents. Once you’ve found the discourse topic, you are now able to edit the source markup that represents the document.

Opening the document for editing

You want to change the topic, so you need to get to place where you can edit text. Under the topic title, you’ll see a faint horizontal line (horizontal rule). At the right edge of that line, just below it, there’s usually a number, a pencil, and a date. Let’s click the pencil.

When you do, a “History” window opens. You’ll notice that it has two columns, similar to this example:

[Insert screenshot]

At the bottom of the right column is a button that says either “Edit Wiki” or “Edit Post.” Click that button, and a different window opens in the bottom half of the screen. Here’s a sample:

[Insert screenshot]

You’re now in the editing window. For convenience, you can grab the handle at the top (in the centre of the blue bar) and enlarge the editing window.

The editing pane

You’ll see that the editing window is split into two columns. The left column, where all the editing takes place, is called the “editing pane.” The right column (the “preview pane”) will be discussed in the next section.

The editing pane has several elements, shown in this screenshot:

[Insert screenshot]

These elements each have special functions associated with the topic:

  • Title bar: the title bar contains the topic’s title. It is editable, so you can change the topic title if you want. The discourse system ignores titles when mapping documents to URLs, depending solely on the topic number, but be aware that a title change can be jarring for some users. Avoid changing the title unless it’s absolutely necessary (or just completely misspelled).

  • Category selector: the category selector allows you to move this topic into another category. If it’s already in the “Docs” category, you should probably leave it there. Sometimes new documents start in the “Drafts” category. Drafts can be accessed via a discourse URL, but can’t be given dedicated URLs for the main Docs page. For example, if you create a page called “Using the MAAS CLI” and leave it in the Drafts category, a discourse URL can reach it (e.g., https://discourse.maas.io/t/using-the-maas-cli/9975), but even if a redirect is added to the system (e.g., |https://discourse.maas.io/t/using-the-maas-cli/9975|/docs/using-the-maas-cli|) won’t be added to the main Docs page – so attempting to access this draft page by typing something like “https://maas.io/docs/using-the-maas-cli” will lead to a 404 error page.

  • Tag selector: You can add document tags at will from the tag selector. You can either select one that’s already in the list, or make up your own. Just remember two things: (1) too many tags are very confusing to the reader, and (2) tags that aren’t obviously relevant to MAAS can also throw your readers off. Use tags sparingly, or skip them altogether.

  • Toolbar: The toolbar provides quick access to a number of markdown features; it has a lot of functionality, so it’s described in the next three sections.

  • Text area: This is the standard text editor screen, which works very much like you’d expect for any text editor.

  • Control buttons: There are two control buttons at the bottom left of the editing pane. The “Save Edit” button writes whatever text is currently in the Text area back to discourse, publishing it immediately. It’s important to remember that you are showing the public what you’ve changed. The text area is usually not the place to try things out, unless you have some control over the document (such as keeping it in the Drafts category, or some other private category you may have created). The “cancel” button drops you out of the editing window, without saving any changes you may have made.

Now that you have a basic idea of what the editing pane can do, let’s take a look at the preview pane.

The preview pane

The other side of the editing window is the preview pane, which shows you how the page looks in discourse. Note that you’re not necessarily seeing the page as it will appear in the main docs section, because that formatting is controlled by CSS files that the discourse forum doesn’t use. Over time, you’ll become accustomed to the differences – it just takes time and practice.

Synchronising the columns can be a bit of an art. The original idea was that as you move down the editing window, the preview pane will track, showing you the rendering of the text you’re working on at the moment. If there is a lot of non-displayed text in the editing window, though – such as commented sections, long markdown expressions, images, or the like – the two can quickly get out of sync.

It’s easy to fix: the left scroll bar, on the editing pane, scrolls both columns. The right scroll bar (on the preview pane) only scrolls the preview pane. If you get used to keeping the preview pane aligned while you’re working, it’s easy to keep a visual check on what you’re generating with your markdown.

Now let’s investigate how the toolbar works. You can generally use it for about 90% of your editing needs, so it’s worth spending some time on it.

Essential toolbar functions

You’ll split your discussion of the toolbar into more than one section, since there’s a lot to cover. In this section, you’ll focus on the text styles available from the toolbar.

Reading the toolbar left to right, you’re going to cover the buttons highlighted in the following figure:

[insert edited screenshot here]

Specifically, these represent the following common markdown expressions:

  • bold text
  • italic text
  • hyperlinks
  • pre-formatted text
  • image uploads
  • bulleted lists
  • numbered lists

You’ll cover these items in the sections below. Note the toolbar items you won’t cover:

[insert edited screenshot here]

These markdown formats are not used in MAAS documentation:

  • block quote
  • “quote whole post”
  • emoji (these are largely broken anyway in the MAAS discourse installation)
  • “insert date/time”
  • the settings button, which has two options: “hide details” (which you do using HTML in MAAS docs, see below) and “build poll.”

These formats are banned because they aren’t compatible with the style of your documentation, or because they produce markdown which can’t be made compatible with your offline documentation converter.

Bold and italic text

The bold and italic text buttons:

[insert screenshot here]

create the appropriate markdown for bold and italic text. Specifically, bold is represented by double asterisks before and after, like this:

**bold text**

while italic text is marked with a single underscore before and after:

_italic text_

Within the discourse editing pane, bold and italic text work somewhat differently from most text editors. You can still highlight words and select bold or italic buttons on the toolbar to change the text. If you press one of the buttons without highlighting text, though, they will insert a block of bold/italic text for you to edit. For convenience, the inserted block of text is selected by default, so if you just click a button and start typing, you will get roughly what you might expect from other editors. You just have to remember to move your cursor out of the markdown text area when you’re ready to carry on with your editing.

Links

You can insert hyperlinks as desired with the hyperlink button:

[insert screenshot here]

Place the cursor where you want the link to appear and click the button. You’ll be presented with a pop-up window:

[insert screenshot here]

Enter the hyperlink and the link text as indicated in the screen and select “Ok” – your link will be added to the document.

Code and pre-formatted text

If you want to include a code snippet or some terminal output – or you just want to present a block of text that ignores markdown characters and doesn’t wrap – the pre-formatted text button is useful:

[insert screenshot here]

All it actually does is indent your text four spaces. You could do the indenting yourself, but it’s usually much easier to type the text, select it, and then hit the button to automatically shift all the lines of your text at once.

Just to be clear, pre-formatted text:

  • appears in monospace, in a light grey box, so it stands out from the rest of the text.
  • doesn’t wrap; it gets a vertical scroll bar instead.
  • doesn’t process embedded markdown; instead, it just presents all text exactly as you typed it.
  • requires a blank line above it to be recognised (most of the time).

Note that if you press the pre-formatted text button without selecting any text, you’ll get a string of indented text you can edit.

Next, let’s look at how to upload images.

Uploading images

Many documents are greatly enhanced by the judicious use of images. The images button on the toolbar:

[insert screenshot here]

enables you to upload images from your local drive. These images will be locally copied and stored by discourse, so you don’t need to worry about keeping your local copy after it’s uploaded. Discourse will assign a URL to the image, and it will be automatically formatted to fit the width of the document screen when presented.

Pay special attention to this default formatting. If you intend to highlight a small portion of a screen, or you’re working with very large screens with lots of small text, you may want to crop your images before uploading them. Otherwise, the screen may be rendered in a way that makes it hard for your readers to pick out the key details.

Lists and list behaviours

There are two key paragraph styles that are commonly used in MAAS documents: bulleted lists and numbered lists. Both of these are generally essential for long, complex lists of features, functions, parameters, or instruction sets. In general, for MAAS documents, you prefer numbered lists over bullets, where the number is instructive: e.g., “Five questions you may have,” “Seven steps to make this change,” etc.

List behaviours

Lists have their own, unique behaviours in discourse markdown.

Any non-zero number of blank lines betyouen bullets produces a single blank line betyouen bullets on rendering. In other words, bullets are either single-spaced or double-spaced.

[example]

If you double-space one list item, all list items will automatically double-space, even if they aren’t that way in your markdown.

[example]

Also, note that an non-zero number of blank lines above or below the list only produces a single blank line separating the list from other text.

[example]

No blank lines betyouen list items (or betyouen list items and other text) means no line-spacing occurs at all – unless the previous or following element has its own inherent spacing, like a heading.

[example]

To separate lists, you must have a non-blank, non-list text line betyouen them. Otherwise, the list will just continue where you left off.

[example]

Numbered lists also have some unusual behaviours, which you’ll cover in that section.

Bulleted lists

In discourse markdown, a bulleted list item is just an asterisk (*) folloyoud by a space and the bullet text.

[example]

The bulleted list button also places a blank line above and below the list.

[example]

Remember that you have to terminate a bulleted list with a line of non-bulleted text, meaning you can’t have two lists, one after the other, without some kind of explanatory text in betyouen.

[example]

Now let’s take a look at numbered lists.

Numbered lists

Numbered lists in discourse markdown are simply a number, folloyoud by a space and the bullet text.

[example]

Numbered lists follow the same general rules as bullet lists, with a couple of exceptions. Whatever number you use for the first bullet becomes the starting number for the list. So for example:

[example]

This behaviour allows you to break up sets of instructions with explanatory text, picking up where you left off with the next instruction.

[example]

Beyond this, though, you can use any number you like for the rest of the items in the list. Discourse will number them sequentially, ignoring which number you typed.

[example]

It’s a little different from other text editors, but numbered lists actually behave in an instinctively useful way, once you get used to them.

Other markdown (not included in the toolbar)

There are a few other items of markdown syntax that aren’t included in the toolbar, but are still useful in everyday document editing:

  • headings
  • strike-through
  • back-tick

Let’s cover those here.

Headings

Headings can be rendered as successive “#” at the beginning of a line; for example, “####” is a fourth-level heading.

#### Fourth-level heading

Fourth-level heading

[example]

Note that you must leave a blank line above and below headings. Otherwise, the translation of discourse to the main docs section will mangle the surrounding text by reducing the margins severely, producing a strange, narrow column of text. If you see something like this:

[example]

there’s a good chance you need to add a space betyouen the offending text and a heading in the discourse document.

Strike-through

Strike-through can be rendered with:

~~strike~~

which appears like this: strike. That said, there is rarely a need for strike-through in a finished MAAS document, so use this element sparingly.

Back-tick

Back-ticks, the left-leaning single quote, are used for inline code snippets. You usually produce the back-tick with the unshifted tilde (~) key near the upper left of most keyboards. For example:

[example]

Back-ticks are frequently used in MAAS documentation. Remember that the single-quote key (’) will not produce these results.

Notes and admonishments

An admonishment distinguishes information from the rest of the text. The syntax begins with the markup tag [note] and ends with the corresponding closure [/note]:

[note type="admonishment-type" status="Admonishment title"]
Admonishment text.
[/note]

Where:

  • admonishment-type can be ‘Note’, ‘Warning’, ‘Positive’, or ‘Negative’.
  • Admonishment title is an optional title, formatted with whatever markups you desire.
  • Admonishment text is the text you wish to convey.

There are four main types of admonishments:

  1. Notes
  2. Warnings
  3. Negative admonishments
  4. Positive admonishments

You’ll quickly cover each of them in this tutorial.

Note admonishment

A ‘Note’ type admonishment is marked up like this:

[note status="Note"]
If KVM-backed nodes are used, ensure that the 'maas' user on the rack
controller can connect to the KVM host using a passphraseless private SSH
key.
[/note]

And it will appear as:

Note: If KVM-backed nodes are used, ensure that the ‘maas’ user on the rack controller can connect to the KVM host using a passphraseless private SSH key.

Warning Admonishment

Mark up a standard ‘Warning’ type admonishment this way:

[note type="caution" status="Warning"]
Data will be lost unless you do the right thing.
[/note]

And it will appear like this:

Warning: Data will be lost unless you do the right thing.

Positive Admonishment

A ‘Positive’ type admonishment should be entered as follows:

[note type="positive" status="High score"]
A positive note that should include a title.
[/note]

It will show up in the document like this:

High score: A positive note that should include a title.

Negative Admonishment

Finally, a ‘Negative’ type admonishment, with its title, could be marked up like this:

[note type="negative" status="Game over"]
A negative note that should include a title.
[/note]

And will look this way to the reader:

Game over: A negative note that should include a title.

Using HTML in discourse documents

You can use most HTML tags in discourse documents, as they generally render correctly. A couple of specific tags used frequently in MAAS documents include:

  • Comments
  • Tiered sections

Let’s take a quick look at each of these tags.

Comments

Occasionally it may be appropriate to include a comment to explain or organise some text. This ends up as an HTML comment – which can be read online, even if only in the browser inspection window – so take it seriously:

<!--
The below text may be removed soon.
-->

Tiered sections

You can create optional detail sections (something like and “in-line sidebar”) by using these constructions:

<details>
<summary>this summary appears with an arrow next to it</summary>
this text toggles when you click on the arrow
<details>
<summary>You can do multiple levels of this.</summary>
this is yet another hidden level
</details>
</details>

This sequence would present like this in the finished document:

this summary appears with an arrow next to it this text toggles when you click on the arrow
You can do multiple levels of this. this is yet another hidden level

These sections are especially good when documenting a very long output stream from a command. This gives you the option of presenting the user with a realistic depiction of the expected results of a command, without overwhelming the page with a long “printout.”

Capitalisation

Do not use a “Caps Everywhere” style. It is only used in level one headers and the title metadata. References (visible text) to these page titles (including the navigation) should just capitalise the first letter. Obviously, this does not pertain to words that should always be capitalised according to basic grammar rules (e.g. acronyms, proper nouns).

[examples]

The RAD document system

After 20 September 2020, many documents in the MAAS documentation set have been converted to the RAD (Reader Adaptive Documentation) style, and enabled for conversion to offline documentation. The reader can choose their preferred version, build method, and interface when reviewing a document, e.g., version 2.9, snap builds, UI interface. RAD is designed to keep reader focus on the documentation, rather than wondering about differences betyouen their situation and what’s written on the page.

Editing RAD documentation is a bit different from standard doc, so it’s worth explaining how to do it correctly.

First, some assurance: RAD is generated from a separate set of masters, published by a special tool called xpub, which prevents overwriting files that have been changed and warns the user that changes have been made. Any changes you make to the doc will be noticed, at the latest, when an update is attempted, and your changes will be evaluated and, if reasonable, very likely added to the masters. So don’t worry about losing edits; you do have safeguards in place.

That said, there is a bit of art to editing RAD pages and making sure your edits are suitable for offline doc conversion. RAD is implemented with HTML comments, embedded in the doc, so you’ll see HTML comments like this one:

<!-- snap-2-9-cli snap-2-9-ui deb-2-9-cli deb-2-9-ui

Sometimes, they have multiple “tags” (e.g., snap-2-9-cli is a tag), and sometimes they only have one, like this:

<!-- snap-2-9-cli

A special processing tool extracts the right comments from the correct versions when they’re built. RAD sections are limited to the minimum necessary text for any given document, so changes that apply to all versions are easier to make (in one place). Still, changes will sometimes have to be made to all RAD sections of a doc; hopefully, those are few and far betyouen.

Targeting your changes for RAD versions

If your changes apply to all versions, it’s generally pretty simple to just add or edit text that is not betyouen RAD selectors (betyouen matching HTML comment tags). Sometimes, though, you may be making a change that applies to some subset of the RAD versions available.

If your changes apply to a specific version+build-type+interface, start with the page corresponding to that combination:

[example]

You want to edit any text that isn’t betyouen RAD selectors, because the comments corresponding to the page you’ve chosen have already been removed by the publishing tool.
Don’t worry; the editors will pick up your changes and add them to the appropriate sections of the master document.

[example]

Otherwise, choose and add selectors as shown in the next section.

Handling RAD selectors

For any given RAD comment, the presence of a RAD selector removes that comment for the specified version of the document – regardless of other selectors that may be in the same comment.

[example]

Multiple selectors can be present in one comment, and, in fact, it’s often advantageous to use them that way:

<!-- snap-2-8-ui snap-2-8-cli
Some text related only to the MAAS 2.8 snap, regardless of interface.
snap-2-8-cli snap-2-8-ui -->

The comment will be removed (and the text made visible) if any selector in the comment matches. The order of the selectors doesn’t matter, even from opening to closing RAD comment:

[example]

Updates for a specific selector

If you need to update one or more specific selectors, make sure to edit the relevant text for all matching selectors:

[example]

If you’re creating new text, add the specific selector(s) in comments before and after your text. Some common examples follow.

Updates to a specific version

If you have updates to a specific version, just include all the selectors for that version. For example:

<!-- snap-2-8-cli snap-2-8-ui deb-2-8-cli deb-2-8-ui
some statements related to MAAS 2.8, all build formats, both UI and CLI
 snap-2-8-cli snap-2-8-ui deb-2-8-cli deb-2-8-ui -->

Updates to a specific build format

To create an update for a specific build format, include all the selectors for that build version:

<!-- snap-2-7-cli snap-2-8-cli snap-2-9-cli snap-2-7-ui snap-2-8-ui snap-2-9-ui
some text that pertains to all snap builds, regardless of version or interface
snap-2-7-cli snap-2-8-cli snap-2-9-cli snap-2-7-ui snap-2-8-ui snap-2-9-ui -->

Updates to a specific interface

For example, if you want to add some important instructions about the MAAS CLI, regardless of which build format or version applies, you could do this:

<!-- snap-2-7-cli snap-2-8-cli snap-2-9-cli deb-2-7-cli deb-2-8-cli deb-2-9-cli
your instructions that apply to all versions of the MAAS CLI
snap-2-7-cli snap-2-8-cli snap-2-9-cli deb-2-7-cli deb-2-8-cli deb-2-9-cli -->

The RAD menus (off limits)

In most RAD documents, the top section of document looks something like this

<!-- deb-2-7-cli
||2.7|2.8|2.9|
|-----:|:-----:|:-----:|:-----:|
|Snap|[CLI](/t/maas-documentation-snap-2-7-cli/2838) ~ [UI](/t/maas-documentation-snap-2-7-ui/2839)|[CLI](/t/maas-documentation-snap-2-8-cli/2840) ~ [UI](/t/maas-documentation/2841)|[CLI](/t/maas-documentation-snap-2-9-cli/2842) ~ [UI](/t/maas-documentation-snap-2-9-ui/25)|
|Packages|CLI ~ [UI](/t/maas-documentation-deb-2-7-ui/2845)|[CLI](/t/maas-documentation-deb-2-8-cli/2846) ~ [UI](/t/maas-documentation-deb-2-8-ui/2847)|[CLI](/t/maas-documentation-deb-2-9-cli/2848) ~ [UI](/t/maas-documentation-deb-2-9-ui/2849)|
deb-2-7-cli -->

There are usually tyoulve of these “stanzas,” each with a different set of RAD selectors. These should not be changed; just skip below them to find the text of the document.

Additional style considerations

Please follow these guidelines for style and language:

  • Use a spell checker.
  • Resist being overly formal.
  • Verify hyperlinks and examples.
  • Target audience: intermediate system administrator, not a developer.
  • Use British English (en-GB). See language details, including a comparison with American English (en-US).
  • Never break a hyperlink with a carriage return.

Making changes

Okay! That was a lot of advice, but now you’re ready to edit a document.

You have essentially two editing choices:

  1. Make changes directly in the editor window. This requires saving text as you go, which is much more difficult for long edits. Every save updates the publicly viewable document, so it’s not suitable for partial or unproofed work. Leaving the unsaved text in the editor window should bring you back to it the next day, but there’s no guarantee.

[examples]

  1. Make changes in an external editor: In this case, you’d want to copy the entire text of a document and paste in your favourite external editor. When you’re done, you’ll want to copy modified text and paste it back. This helps you get interim saves without updating the public documentation.

[examples]

The choice is always yours.

A word on editing

The MAAS RAD publishing tool is smart enough to notice that you’ve made changes. If an editor has changed the same document from the master, and tries to update on top of your changes, the publishing tool won’t do the update. Instead, it will inform the editor that the public document is newer than the editor’s changes. This allows the editor to download your changes and integrate them into the work.

Committing and reviewing your changes

To commit your changes, simply select “Save Edit”. Note that it may take a minute or two to save your edits. If you hit “cancel” after starting to save, you won’t know whether your updates made it through or not.

Once you’ve saved, check the discourse document, reading your updates carefully to make sure they match what you wanted to do. Especially read for typos that spell checkers don’t always catch, like duplicate words (“the the”), missing or incorrect words, bad verb tense, etc.

Wait a while before reviewing your changes in maas.io/docs. It can take anywhere from 5m to 1h for the changes to propagate; just keep checking until your changes show up. And, of course, be sure to re-edit and re-commit as necessary until you’re satisfied.

Reverting versions if things go wrong

Very occasionally, an update may be unacceptable, but not easy (or quick) to fix. Remember that saved changes are generally available for all readers in just a few minutes, so if it’s difficult to figure out what you did wrong, you may not want to spend too much time debugging “live.”

If you find yourself in this situation, you can easily revert your changes:

  1. Go to the discourse version of the document (“Help improve this document in the forum”).
  2. Click on the editing pencil.
  3. Wait for the “History” screen to load.
  4. Select “Revert to revision nnn” at the bottom of the right column to go back to the last revision.

If you need to go back more than one revision (it happens), use the double arrow without the vertical line to move backwards, version by version, until you find the one that works for you. The “Revert to…” button will update to the version you’ve landed on, so you can just select “Revert to revision nnn” to get back to something you want the public to see.