Reference: Documentation style guide

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.
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.

This topic was automatically closed 365 days after the last reply. New replies are no longer allowed.