Becoming a MAAS documentation pro
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.
Getting started with contributions
Ponder the following:
If your answer to all these is yes, then you're on the right path.
The art of crafting with style and precision
Consistency and style are the lifeblood of readability and engagement. Here's a blueprint to guide your writing endeavors:
While the document markup may seem daunting, it's refreshingly intuitive. Let the formatting bar be your beacon, guiding your editor interactions.
Utilising headings and text styles
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:
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.
<strong>Bold</strong>
<em>Italic</em>
or
**bold**
*italic*
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] tag:
[note]
Your essential information here.
[/note]
This will produce a setoff box, like this:
[note] Your essential information here. [/note]
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"><i-mg 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>
Narrative nuances: The secret sauce of engaging content
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."
Engage with relatable comparisons
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:
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!