Reference: Documentation style guide

- Configure controllers
- Enable high availability

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

This page describes the MAAS documentation style in a concise table.

Element	Guidelines
Spelling and Grammar	Use British English (en-GB), and ensure correct spelling and grammar.
Voice and Tone	Use a compact, conversational style. Write to the reader directly.
Hyperlink Hygiene	Ensure all hyperlinks are functional and relevant.
Audience Focus	Target intermediate system administrators; avoid overly technical jargon.
Headings	Use standard HTML. Capitalise only the first word unless it’s a proper noun. Self-anchor headings.
Text Styles	Use HTML or markdown for bold (`<strong>`, `bold`) and italics (`<em>`, `italic`). Use sparingly.
Code Formatting	For blocks, use four-space indentation or triple-backtick. For inline, use `<code>` or backticks.

Spelling and Grammar

Use British English (en-GB), and ensure correct spelling and grammar.

Voice and Tone

Use a compact, conversational style. Write to the reader directly.

Hyperlink Hygiene

Ensure all hyperlinks are functional and relevant.

Audience Focus

Target intermediate system administrators; avoid overly technical jargon.

Headings

Use standard HTML. Capitalise only the first word unless it’s a proper noun. Self-anchor headings.

Text Styles

Use HTML or markdown for bold (<strong>, **bold**) and italics (<em>, *italic*). Use sparingly.

Code Formatting

For blocks, use four-space indentation or triple-backtick. For inline, use <code> or backticks.

Highlights and Comments | Use `` for important info. HTML comments are visible in browser inspections. |
Linking and Embedding | Format hyperlinks as [text](URL). Embed images with appropriate context and cropping. |
Interactive Content | Use <details> and <summary> for collapsible sections. |
Paragraph Writing | Keep paragraphs concise. Use active voice. Use relatable comparisons. Vary sentence structure. |

Pro tips

Brevity is key: Keep sentences short and to the point. Just say it.

Active voice: Talk to the user. Use active rather than passive voice for clarity.

Clear comparisons: Complexity loses readers. Use simple, relatable comparisons to explain concepts. You’re teaching, not boasting.

Conversational Rhythm: Mix short sentences with longer explanatory ones.