Magalix recently launched the Write for Cloud-Native Program. It supports engineers and community members who have experiences and knowledge to share with the rapidly growing cloud-native community. The content will be shared with thousands of readers on the Magalix blog, and writers will be paid $200 per article, up to $350 depending on depth and quality.
Magalix is excited to continue building out its collection of technical articles related to server administration and software engineering. To ensure that Magalix articles have consistent quality and style, we have developed the following guidelines.
There are three sections in this guide:
- Style, our high-level approach to writing technical articles
- Structure, an explanation of our layout and content
To get published quickly, Magalix community authors should read the style and structure sections in their entirety. Our templates are useful as a starting point for an article.
Magalix articles should follow Magalix style guidelines as explained below.
Comprehensive And Written For All Experience Levels
Our articles are written to be as clear and detailed as possible without making assumptions about the reader's background knowledge. If the article requires specific prior knowledge, please make sure you explicitly mention this as early as possible in the article.
We explicitly include every command a reader needs to know from their first connection on an existing Kubernetes cluster to the final, working setup. We also provide readers with all of the explanations and background information they need to understand the tutorial or the guidelines. The goal is for our readers to learn from our posts, not just copy and paste.
Technically Detailed And Correct
All of our tutorials are tested on fresh Kubernetes clusters to ensure that they work from scratch. Every command should have a detailed explanation, including options and flags as necessary. When you ask the reader to execute a command or modify a configuration file, first explain what it does and/or why they're making those changes.
Practical, Useful, And Self-contained
Once a reader has finished a Magalix article, they should have installed or set-up something from start to finish. We emphasize a practical approach: at the end of an article, we should leave the reader with a usable environment or an example to build upon.
What this means for the writer is that their article should cover the given topic thoroughly and, where necessary, should link to another Magalix article to set up prerequisites. Authors shouldn't send readers offsite to gather any information that could easily be added to the article.
The Plain Voice Method - Friendly But Formal
Our tutorials aim for a friendly but formal tone. This means that articles do not include jargon, memes, or excessive jokes. This also means that, unlike blog posts, we do not use the first person singular (e.g., "I think ..."). Instead, we use the first person plural (e.g., "We will install ...) or second person (e.g., "You will configure ...").
A Focus On The Reader
Talk to readers using plain voice, a way that’s warm and relaxed, crisp and clear, and ready to lend a hand - it reflects a commitment to empowering people to achieve more. Make it easy and comfortable to glean the info.
Our voice is:
- Warm and relaxed - Write naturally. Formal where needed, but more grounded in real, everyday conversation.
- Crisp and clear - We’re to the point. We make it simple and clear above all.
- Ready to lend a hand - We show customers we’re on their side. We anticipate their need to easily pick up great information.
- Written for a team atmosphere – As stated above, wherever it’s possible we use “we” and “our,” instead of “I” and “mine.” It’s about the team dynamic.
A few key elements of writing with plain voice:
- Get to the point fast. Easily show the key takeaways. Put the most important things in the most noticeable spots. Make choices and next steps obvious. Give people just enough information to make decisions confidently - don’t get in the way of the message.
- Talk like a person. Choose optimistic, conversational language. Use short everyday words, contractions, and sentence-style capitalization.
- Simpler is better. Everyone likes clarity and getting to the point. Break it up. Short sentences are easier to scan quickly and read. Prune every excess word to make it easy for the reader.
Magalix articles have a consistent structure comprised of the following sections:
- Goals (Optional)
- Step 1 — Doing the First Thing
- Step 2 — Doing the Next Thing
- Step n — Doing the Last Thing
Nitty-Gritty Formatting Fonts & Other Boring Stuff:
- Headers & Sub-headers: each word capitalized for ease of use (i.e., Title Caps, as seen in this guide).
- Headers are font size 20.
- Sub-headers are font size 16.
- Body text is font size 11.
- One single space from the body to the next header or sub-header (unless you actually have Chapters).
A typical title follows this format: How To <Accomplish a Task> with <Software> on <Distro>.
When you write your title, think carefully about what the reader will accomplish by following your tutorial. Try to include the goal of the tutorial in the title, not just the tool(s) the reader will use to accomplish that goal.
Introduction And Goals
The first section of every tutorial is the Introduction, which is usually 1 to 3 paragraphs long.
The purpose of the introduction is to answer the following questions for the reader:
- What is the goal of the tutorial? What will the reader accomplish if they follow it?
- What software is involved, and what does each component do (briefly)?
- What are the benefits of using this particular software in this configuration? What are some practical reasons why the reader should follow this tutorial?
Some tutorials use the optional Goals section to separate the tutorial’s context, background explanation, and motivation from the details of the final configuration. You should only use this section if your tutorial requires multiple servers, has a large software stack, or otherwise has a particularly complicated purpose, method, or result.
The Prerequisites section of an article has a very specific format and purpose.
The purpose is to spell out exactly what the reader should have (or do) before they follow the current tutorial. The format is a bulleted list that the reader can use as a checklist. Each bullet point must link to an existing DigitalOcean tutorial that covers the necessary content. This allows you to rely on existing content known to work instead of starting from scratch.
Common prerequisite bullet points include:
- The number of servers necessary, including distribution, initial server setup, and any additional necessary options (like memory requirements, DO API keys, IPv6, or private networking).
- Software installation and configuration.
- Required DNS settings or SSL certificates.
- Additional user accounts like GitHub, Facebook, Twitter, or other services your reader will need.
When you test your tutorial or concepts, make sure you follow all of the prerequisite tutorials exactly as written so that everyone uses the same starting point. If you changed a variable or completed an optional step from one of the prerequisites, make sure to note that.
The Steps sections are where you describe exactly what the reader needs to do. Begin each step with an introductory sentence that describes what the step covers and what role it plays in achieving the overall goal of the tutorial. End each step with a transition sentence that describes what the reader accomplished and where they are going next. Avoid repeating the step title in these introductions and transitions, and don’t start or end steps with contextless instructions, commands, or output.
All commands in a step should be on their own line in their own code block, and each command should be preceded by a description. Similarly, always introduce a file or script by describing its general purpose, then explain any changes that the reader will be making in the file. Without these explanations, readers won’t be able to customize, update, or troubleshoot their server(s) in the long run.
The Conclusion should summarize what the reader has accomplished by following your tutorial. It should also describe what the reader can do next. This can include a description of use cases or features the reader can explore, links to other DigitalOcean tutorials with additional setup, configuration, and external documentation.