Help Document Design for Non-Designers

Mathew Patterson | October 3, 2017

No matter which knowledge base software you use, building and maintaining a knowledge base can be 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 was very hard to make our designer create this atrocity.

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.

A subtle grey background creates contrast.

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

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.

Larger margins and increased line height improve reasability.

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.

Taking the font size from 14px to 16px reduces reading effort.

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.

Headings visually break up longer sections.

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.

Simple list styling makes them really stand out.

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.

A contrasting callout draws the reader's eye.

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.

Screenshots show readers exactly what you mean.

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.

The final product is vastly more likely to help!

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.

Mathew Patterson

After running a support team for years, Mat joined the marketing team at Help Scout, where we make excellent customer service achievable for companies of all sizes. Connect with him on Twitter and LinkedIn.