Documentation style guide

Mind the details, but don’t get stressed out; our editors are happy to help

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

This reference-style guide provides a concise overview of the MAAS documentation style, focusing on key elements to ensure consistency and readability. In fact, let’s keep it simple with a quick-reference table:

Element Guidelines
Spelling & Grammar Use British English (en-GB), and ensure correct spelling and grammar.
Voice & Tone Maintain a compact, conversational style. Address 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 & Comments Use [note] for important info. HTML comments are visible in browser inspections.
Linking & 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. Employ 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 impactful sentences with longer explanatory ones. We’ve done that here.

This guide serves as a quick reference for contributors. These standards are pretty simple. Follow them, and you’ll write quality documentation.

Last updated a month ago.