Today, I stumbled upon DigitalOcean’s Technical Writing Guidelines. Some of their guidelines really struck a chord with me, reminding me of the importance of clear, concise writing.
I’ll be honest, I might not have followed all these guidelines in the past. But from now on, I’ve decided to keep a close eye on these. When I write new posts, I’ll make a conscious effort to incorporate these guidelines. I have listed them below.
- “Our tutorials aim for a friendly but formal tone. This means that articles do not include jargon, memes, excessive slang, emoji, or jokes.”
- “Unlike blog posts, we do not use the first person singular (e.g., “I think …”). Instead, we encourage the use of the second person (e.g., “You will configure …”) to keep the focus on the reader and what they’ll accomplish. In some cases, we’ll use the first person plural (e.g., “We will examine …”).”
- “We avoid words like “simple,” “straightforward,” “easy,” “simply,” “obviously,” and “just,” as these words make assumptions about the reader’s knowledge. While authors use these words to encourage and motivate readers to push through challenging topics, they often have the opposite effect; a reader who hears that something is “easy” may be frustrated when they encounter an issue. Instead, we encourage our readers by providing the explanations they need to be successful.”
- “Every command should have a detailed explanation, including options and flags as necessary. Every block of code should be followed by prose explanations that describe what it does and why it works that way. When you ask the reader to execute a command or modify a configuration file, first explain what it does and why you’re asking the reader to make those changes. These details give readers the information they need to grow their skills.”