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.