Words at work

– 7 min read

5 rules for creating a truly helpful knowledge base article

Writer Team

Writer Team

Nobody likes to wait for customer service to get back to them. And they definitely don’t like to wait when they have a problem that needs to be resolved. In fact, 88% of consumers expect brands to have a customer support self-service channel. That includes a helpful, clearly written knowledge base.

Unfortunately, many companies disappoint users with boring, confusing, and poorly written knowledge center content. Customers can’t resolve their own problems and are left with a negative impression of the brand. In the end, both parties lose. Customers aren’t equipped to resolve their problems, and brands lose an opportunity to build loyalty and save time on customer support.

Engaging, well-written help documentation can be the secret sauce of brand loyalty. Following a few rules, your team can write clear, effective knowledge base articles that empower your customers — and make life easier for your support team.


1. Understand the problem from the user’s perspective

At times, the more knowledgeable you are about a topic, the more difficult it is to explain to the reader. Technical writing can easily fall prey to use of jargon and high-level language that confuses the non-expert reader.

To write well about a technical topic, you’ve got to understand the problem from the user’s perspective. Don’t think about it from the perspective of an expert (you); think about it from the perspective of a total beginner (the user).

To avoid “thinking like the expert”:

1. Avoid making assumptions about what the user already knows about your product, your user interface, and even terminology. Define even the simplest terms in case your readers don’t know them. (Take a look at how Cleo defined “ecosystem” in this article).

2. Don’t cut corners. Explain all steps involving the user interface and user flow (i.e., “Return to user dashboard, located on the upper right-hand corner”).)

3. Observe users in action (if possible). What do they click on first? How do they input data, make changes, and save information? Where do they seem confused?)

Make sure you have a rich understanding of user experience (UX)—not only the intention for the design but how users are actually using your product.

2. Use plain language

Readers are 38% more likely to understand your text if it’s written in plain language, with the average U.S. adult reading at a 7th-8th grade level. Likewise, they are 41% more likely to remember information.

Resist the temptation to prove your expertise with overly sophisticated language and instead aim for plain language.

Plain language includes:

Commonly used words. Most of us use the same 1,000 words most of the time. Aim for words that fall within the range of “common language” (for example, repair instead of fix).

Straight forward sentence structure. Break up long sentences and focus on short imperatives.)

Active voice. Avoid using the passive voice (“The website was built”). Aim for the active voice (“Build the website”).)

You can use Writer’s editor tool to determine the grade level your language falls under. The below example from a Zendesk knowledge base article received a grade level of 10. Depending on their reader demographics, they may decide to adjust their language so it appeals to readers who prefer to read slightly lower grade levels.

A screenshot of a Zendesk help center article pasted into the Writer editor tool.
A screenshot of a Zendesk help center article pasted into the Writer editor tool.

3. Use visual elements along with text descriptions

65% of people are visual learners. They learn by seeing something in action, not just by hearing about it (or reading about it). Combining visual elements with text descriptions can be a helpful strategy for writing a good knowledge base article.

One of the biggest challenges of writing a knowledge base article is explaining the user interface (UI). Don’t jump through hoops to explain features of your UI; instead, use screenshots, videos, and other visual elements to make life easier for your readers (and you).

Asana is a perfect example of a company that uses annotated visuals in their knowledge base articles to clearly explain their interface.

Asana's interface

4. Break up text with section headers, bullet points, and lists

80% of readers don’t fully read online content. Even when they’re trying to learn something new, your users will likely “skim” your articles to pick out information that’s most relevant to them. To keep the attention of your readers, guide them through articles with section headers, bullet points, and lists.

One clear example of this kind of copy is in Zendesk’s article on “Creating categories to organize triggers.” In this knowledge base article, Zendesk:

Presents the content of the article in a bullet point list with links.

Uses short paragraphs and screenshots, when applicable.)

Divides the information into categories to help readers quickly locate what they need to know)

To effectively use section headers, bullet points, and lists, think through how to logically divide your topic into subcategories and what readers will need to know first.

Let’s say you are writing an article on “How to Create a Drop Down Menu” for your website creation.

First, you may want to write a step-by-step list on how to create a menu from scratch (screenshots may be helpful here). Then, you may want to write a few additional subcategories with information about how to add a category, delete a category, or change the placement of the menu.

In any case, think through the UX of your article and use formatting to make the experience of reading smooth, intuitive, and delightful.

5. Establish a consistent style for all knowledge base articles

Brand consistency is key. Your site, content, and marketing assets have the same tone, look, and feel. That should apply to your knowledge base as well.

To create brand consistency for your support articles, you’ll need to use a similar style for all articles. That includes:

Information layout. Your article sections and paragraph length should be consistent throughout your knowledge base. If you use lots of short paragraphs, for example, then keep that style across all articles.

Font, font size, and type style.Double check your articles to make sure they maintain the same font style throughout.)

Tone.Is your website and marketing content written in playful, quippy language? Or are they more straightforward and formal? Use the same tone in your knowledge base that you use everywhere else.)

Lexicon. Depending on the complexity of your product, you may use unique terminology or special phrases to describe your product and product experience. Make sure to solidify your vocabulary before writing support articles. If you use the term “user interface” in your product description, then use the same term in your articles. Or, if you use the term “primary dashboard,” then use that.)

On a team, maintaining consistency in style and language can be challenging. Tools like Writer will help keep you and your team in check. Whether you are writing an article, a script, or a social media post, Writer will save you time and energy during the editing process.

Users get to know and love the host’s playful tone as they joke and banter with guests. The article always addresses the reader directly, using “you” and “your,” and provides quick, clear solutions. This consistent quality builds a sense of trust and familiarity in users, so they feel comfortable turning to the knowledge base for answers.

Anyone can create a great knowledge base

A great knowledge base does more than help educate your users. A great KB also saves you labor and time on active support, builds loyalty among your users, and positions you as an expert.

The good news is that you don’t need a professional writer to create a great knowledge base for your product. You simply need to keep a few guidelines and strategies in mind. Empathize with your users. Write in clear language. And keep it consistent.

Writer can help equip your team to make clear, consistent, well-written customer support content. Start your free trial today.

Writer logo

Align your product, marketing, and support teams around a consistent content strategy.

Talk to us for a product tour.