MAAS documentation style guide

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; capitalize 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

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.