Documentation style guide
Welcome to the world of MAAS documentation. As you embark on this journey, you’ll discover the nuances of creating effective and engaging content for our community. This guide will arm you with the techniques and standards to excel in your contributions.
Ponder the following:
- Will your contribution elevate the conversation?
- Are you being considerate and respectful to other community members?
- Is your feedback constructive and focused on ideas rather than individuals?
- Are you confident in the technical correctness of your contribution?
If your answer to all these is yes, then you’re on the right path.
Consistency and style are the lifeblood of readability and engagement. Here’s a blueprint to guide your writing endeavors:
- Spelling & Grammar: Never underestimate the power of spell check. Grammar, though often subtle, significantly impacts reader comprehension.
- Voice & Tone: Cultivate a compact, conversational cadence. Engage readers as though they’re right beside you.
- Hyperlink Hygiene: A dead link is a reader’s dead-end. Validate each hyperlink, ensuring they guide the reader as intended.
- Audience Alignment: Speak to the intermediate system administrator. Your content isn’t developer-centric; it’s about making admins’ lives simpler.
- Language Consistency: British English (en-GB) is your lingua franca. Imbibe its nuances, spelling, and structure.
- Hyperlink Integrity: Always ensure hyperlinks remain seamless; avoid fragmentation at all costs.
While the document markup may seem daunting, it’s refreshingly intuitive. Let the formatting bar be your beacon, guiding your editor interactions.
Headings and text styles give Canonical documentation a distinctive look-and-feel.
For Canonical documentation, we don’t use “title case.” Capitalise only the first word of a heading, unless it incorporates a word that is normally capitalised. For example:
How to install the latest version
MAAS monitoring tools
Using Terraform with MAAS
Also, use standard HTML for your headings, like this:
<h2 id="header--unique-id">Sub-heading about something</h2> <h3 id="header--a-different-unique-id">Sub-sub-heading about details about that something</h3>
Note that the style “header–” is required by our Discourse server to be recognized as an ID.
We strongly prefer that you self-anchor your headers:
- A simple click will bring that section to the top of the browser window.
- Users can easily bookmark particular sections for ready reference.
You can create these self-anchored headings like this:
<a href="#header--unique-id"><h2 id="header--unique-id">Sub-heading</h2></a>
Employ standard HTML or Discourse markdown for bold and italics.
A word to the wise: use them sparingly – it’s more readable.
For blocks of code or pre-formatted text, use four-space indentation or the triple-backtick “code block:”
maas command example
For inline code snippets, employ the
<code> tag or a backtick:
Use the `<code>` tag or `backtick` for inline code.
Highlight significant information using the
[note] Your essential information here. [/note]
This will produce a setoff box, like this:
Your essential information here.
Occasionally, you might want to add an HTML comment. Remember that these are visible when inspecting browser elements:
<!-- Insert your comment here. -->
For hyperlinks, use the following format:
[Your anchor text here](Your URL here)
When embedding images, remember context is key. Use appropriate cropping. Place images in the
uploads directory, and use a consistent naming and linking convention:
<a href="URL_to_large_image" target="_blank"><img src="URL_to_thumbnail"></a>
Interactive details and tiered sections provide an engaging experience for readers. These can be created with the following structure:
<details> <summary>Your clickable summary here</summary> The content hidden by default. </details>
In the realm of technical documentation, the narrative isn’t about storytelling in the traditional sense. Instead, it’s about presenting information in a manner that’s engaging, accessible, and digestible. The difference between a mediocre document and a great one often lies in the subtle nuances of its narrative. Let’s consider some examples.
Brevity is a welcome gift. Compact, crisp sentences are the hallmark of effective technical writing. They convey essential information without burdening the reader. It’s tempting to provide exhaustive details, but remember that every word should earn its place:
Good: “MAAS accelerates server deployment with intuitive workflows.”
Bad: “When you start to use MAAS, you will find that due to its very well-thought-out design, the process of deploying servers can be faster than traditional methods because of its user-friendly and intuitive workflows.”
Using active voice infuses energy. Your writing becomes direct and clear, and the reader doesn’t get lost:
Good: “The MAAS CLI deploys servers efficiently.”
Bad: “Servers are being deployed by the MAAS CLI in an efficient manner.”
Abstract concepts can be hard to grasp. Simple comparisons anchor unfamiliar ideas to familiar concepts, bridging understanding. Just remember to keep the comparisons simple – if the comparison takes more space than the point you’re trying to make, you’re doing it wrong.
Good: “MAAS is a multi-tool that coordinates different server tasks.”
Bad: “Think of MAAS as the conductor of an orchestra, harmonising server operations into beautiful technical music.”
Compact is essential; variety maintains engagement. Mix shorter, impactful statements with slightly longer, explanatory ones. This is sometimes called “conversational rhythm”, and it makes writing more palatable.
Good: “MAAS eases server management. With its robust toolset, you can navigate the complexities of infrastructure seamlessly.”
Bad: “MAAS is a revolutionary tool that changes the way server management is approached and has a robust toolset that aids in navigating the intricacies of managing infrastructure.”
Before diving in, you need to know the foundations of editing. Once you’ve secured the permissions:
- Choose the “Help improve this document in the forum” link found at the bottom of articles.
- Understand that your edits are live the moment they’re saved. Accuracy and attention to detail are paramount.
By mastering narrative nuances, you’re not just providing information; you’re crafting an experience. And in that experience, readers find clarity, understanding, and the confidence to engage with the technology you’re documenting.
Armed with these insights, you’re poised to enhance our documentation. Dive in and make a difference!