Building and maintaining a knowledge base is hard work. Getting your customers to visit the knowledge base before asking for help can be even trickier! So don’t let all the effort go to waste by hard to read or visually unappealing documents.
Even if you’re lucky enough to have access to skilled designers, being design literate yourself will improve the structure and layout of any document you work on.
Redesigning a sample help document
To best illustrate good document design, let’s start with a typical “knowledge lump” design. All the information on the page is accurate and useful, but the design is really letting it down.
It’s hard to scan and unappealing to look at, and it’s likely that even people who would benefit from the information it contains would give up before reading it all. In this article we’ll take this document step by step through simple design improvements until we end up with a help page that’s vastly more readable.
Principles of document design
Contrast just means “difference,” and it’s a basic principle of design. For our sample document, that starts with giving the text a color that stands out from the background. We’ll use a plain background, avoiding textures or images that conflict with the text.
Already, it’s much easier to read, especially for the majority of people who don’t have perfect eyesight. We’ll use contrast again as we consider headings and callouts later on in our guide.
White space refers to empty space around and between page elements (like text, page margins and images), whether it is actually white or not.
A 2004 study by D.-Y.M. Lin found that the use of white space between paragraphs and in the left and right margins increased comprehension by almost 20 percent for older readers.
So let’s add some margins around our document, increase the line spacing, and separate our paragraphs a little.
Make your text larger
The all time record holder for most common complaint about websites is “the text is too small!” Of course your wonderful young eyes probably have no trouble at all reading microscopic text, but the rest of us appreciate something a little larger.
A good minimum font size to shoot for is 16px, although it’s the combination of font face, size, and line height that make up the overall readability level.
Historically, sans-serif font faces (Arial, for example) were more readable on screen, but higher resolution monitors have greatly reduced the differences.
Use headings for scannability
Break up long blocks of text with headings so that readers can more easily find just the section they are after. A heading with sufficient contrast and white space is a nice landing place for the reader’s eyes, and it can help them decide whether to invest more time on the page.
In our sample document, adding a few headings makes the overall content of the page much more obvious at a glance.
Use bullets, lists and anchors
Identify parts of your document that can be converted from prose into bullet points or numbered lists. If you have a set of steps that customers need to follow, or a few critical pieces of information to impart, those are great candidates for a list.
If your page is fairly long, consider adding a table of contents at the top. A well-written table of contents helps readers quickly understand what the document covers and allows them to jump directly to the information they need.
Extract key quotes
For quotes or important nuggets of information that stand alone (and aren’t part of a list), pulling them out of the text flow into a pull quote will make them easy to spot. In our example, we’ve emphasized the key step in the process to switch on their auto-reply settings.
Use screenshots and GIFs
Wherever possible, using a screenshot to show what you mean rather than laboriously describing it in text makes help documents more effective. In our example, we can greatly simplify our explanation by referring to the screenshot.
A good help document screenshot should:
- Be large enough to be easily readable. You may need to crop a screenshot to keep the key information at a reasonable size while fitting into your page
- Contain visual context, so readers understand what they are looking at. Don’t crop too tightly!
- Be annotated where appropriate (consider labeling items if you refer to them in your copy)
The same rules generally apply for animated GIFs and videos too.
Implementing design improvements
Depending on the knowledge base or CMS system you’re using, many of the visual styling improvements can be made through CSS changes and will apply across all your documents.
For structural improvements like lists and headings or for screenshots and videos, you have a little more work ahead of you. Be sure to watch our interview with the Campaign Monitor technical writing team to learn from their approach to a big knowledge base redesign.