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.