If you write knowledge articles and instructions, you know there’s plenty to pay attention to: Are all necessary steps described, are all details correct, is everything up to date, do you need to include code snippets or flow diagrams…? With so many aspects to juggle, it’s normal that focus can drift away from the essential factor: your reader. To help set the focus back on them, here’s a checklist of easy ways you can make your knowledge articles and instructions easier and faster to read. Help your readers get through their workday with more success and less frustration with simpler knowledge articles.
Typically, readers of documentation are in a hurry to find information or instructional steps. Don’t drag things out. Keep it short and simple. That includes:
- Simple language: Short sentences and simple language make text easier and faster to skim and understand. If you can break a sentence into several, do so. If you can replace a complicated word with a simple one, that’s good. Don’t be afraid you’re coming off as belittling or boring to your readers when using simple language. They’re reading your knowledge article not for entertainment, but to quickly find what they’re looking for.
- Limited vocabulary: Try to use the same word for the same thing throughout the whole article or instruction. It might seem repetitive, but it helps follow the instruction more easily and it’s also great for readers using the search function.
- Leading sentence structure: This means structuring the words in your sentences so that the parts that help readers most to orient themselves or that happen first appear in the beginning of the sentence.
Guide the eye
Not only the language can make your knowledge article simpler: Making it visually easy to segment the content makes both reading and skimming much faster.
- Give an overview: Especially for longer pages, offer an interactive table of contents with links that can take the readers straight to the parts they need.
- Break up text with structure: Short paragraphs, headings and structuring elements like lists help with skimming content and quickly finding what you’re looking for.
- Highlighting: Use things like bold text or colors to help the eye find the important parts. But try to keep it balanced. If every second word is an eye-catcher, it won’t be helpful to the reader anymore.
Stick to conventions
Try to stick to common conventions to make reading your content more intuitive, such as:
- Common terminology to refer to things rather than customized names
- Familiar color schemes like red for things that are negative and green for things that are positive
First of all: You do not have to use illustrations. If the content doesn’t need them or they might even make things more confusing, there’s no need to come up with a visualization or to add stock pictures. You want a simpler knowledge article, not a more cluttered one.
But if your content can benefit from an illustration, consider these tips:
- Which type of illustration best matches the content: If you’re displaying a process, you likely want to use a flow diagram; if you have data to show, use a chart; if you show how to operate an application, use a screenshot.
- Declutter: Only include what is necessary, so the illustration can be understood quickly and without further explanation.
- Give a key: If the illustration does need an explanation, be sure to give one. Let the reader know what different colors, symbols and columns stand for.
- Make your illustration accessible: You can help not only users with visual impairments but all your readers by making your illustrations more accessible. Make sure all details are clearly visible and explained. Put further explanations in the text, so they’re searchable.
Ask your readers what they need in a simpler knowledge article!
Sometimes it’s hard to decide what the best way of describing a specific information or instruction is or how to optimize your knowledge article further. If you struggle, focus on the readers’ perspective.
- Note down a reader persona: Noting down some typical attributes your readers have can help you focus on them and their needs.
- Ask a colleague: Getting a second perspective can always help make improvements. Your colleagues might not be your readers, but they can still help you find parts that could be explained more clearly or have good ideas for simplifying an illustration.
- Ask a reader: Lastly, of course, ask your readers what they think. This doesn’t have to be before publishing. Feedback can also be collected via reviews, comment or contact forms. All of these offer valuable input, not just for the content you just published, but for future knowledge articles, too.
There’s a lot of details to branch out to from this general overview: tips for limiting vocabularies, highlighting rules, a bigger look at web conventions or accessibility guidelines. Stick around for more articles coming soon, helping you make the perfect content for your readers’ needs.
Did we miss something you always do to help your readers? Send us an email to firstname.lastname@example.org and let us know!