Tips for Writing Knowledge Articles

Overview

Along with using the existing knowledge templates, here are some tips to help you write good knowledge articles.

• Tell and Show, Don’t Only Tell: People learn in a wide number of ways. Whenever possible, add screenshots, animated GIFs, or even videos to make it easier for readers to follow along. Images should be included after the text describing/referencing it.
• Start with the Easiest First: If there are multiple steps required to complete a task, always start with the easiest steps first. This allows customer to get at least one accomplishment under their belt before moving on to harder steps. This usually means breaking up a long and complex article into multiple shorter and simpler articles. When doing this, make sure to include a Next Steps section that provides link(s) to the next immediate article in the series progression.
• Use the Right Tone: Be straightforward and avoid jargon whenever possible. Remember, your main goal is to communicate information. Always consider the customer’s mindset when writing, if they’re referencing an article about a frustrating error message, the article’s tone should probably avoid light hearted humor.
• Avoid the Curse of Knowledge: Put yourself into a beginner’s shoes when writing knowledge base articles. Not everyone has the same depth of knowledge on a topic. Try to avoid skipping over steps you might consider obvious, this enables someone less familiar with the technology to follow along to the desired result.