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. |
| 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. |
Tips for writing tight paragraphs
This guide serves as a quick reference for contributors. These standards are pretty simple. Follow them, and you'll write quality documentation.