Last updated on Jan 20, 2021
An important part of writing support documentation is how you present it to your users.
Why? Surely only content matters.
The reason presentation matters is because a professional image helps to build trust and inspire confidence in your users. It also makes your content easier to use.
It’s possible that you have some help content already, but it’s a bit of a mismatch. Your knowledge base has grown organically over the years, and it has been drawn from different sources. That’s not a problem – but, eventually, every knowledge base needs its own style guide, so you can keep content consistent and professional.
Style guides are especially handy when you have multiple contributors to your content who may not be privy to all of your goals and decisions. You are making the implicit explicit with your style guide.
So what should you cover in your style guide?
Knowledge base style guides deal with the presentation aspects of your content: voice & tone, format, words, layout.
Many different content sources have their own style guide, but SaaS knowledge bases include some very specific types of content. It’s important to remember that there are different types of documentation you can write, ranging from: tutorials, how-to guides, explanations, and references.
There are numerous things you will need to cover for a comprehensive style guide, which we’ll go over in detail in this article. Pay particular attention to the word “guide” – which means you are providing a template for writers, rather than creating a hard and fast book of law.
Here’s a timeless quote from one of the english writing greats:
“Break any of these rules sooner than say anything outright barbarous.” —George Orwell, Politics and the English Language
When creating your user documentation, one of the main content types you are likely to run into is the tutorial.
Tutorials are step-by-step guides that are focused on introducing one topic, or a small group of closely related topics. It’s learning-oriented, and allows the beginner user to get started with your software.
Think of a tutorial as like a lesson that teaches the user how to do something.
You decide what to teach your user, with the goal of getting them up and running as quickly as possible with your software. Every tutorial should produce a tangible result for your users that introduces them to the basic processes of using your software.
It should be written in a step-by-step format. Each step should be practical and result in user-visible progress – as opposed to purely theoretical learning.
Analogy: think of a driving lesson for a new driver, learning the basic functions of the car like starting the engine, changing gears, and braking.
Software example: Create your first knowledge base in Document360
Here are some basic rules for tutorial writing:
Some examples of great tutorials are:
Next, we’ll look at how to write a how-to guide.
A how-to guide seems similar to a tutorial, but is actually aimed at solving a specific problem or issue with the software.
How-to guides are goal-oriented and presented as a series of steps, and can be seen more as a troubleshooting type of content. These articles require some pre-existing knowledge of the subject matter from the user, and are designed to achieve a specific end.
They are usually aimed at the more experienced user who wants to know how a particular aspect of your software works. The key focus here is consistency and clarity. You must adhere to typical conventions when your writers refer to elements of the UI, for example.
It’s important to remember that users are working from many different types of hardware device, browser, or operating system, so you’ll need to format your instructions to take into account all possibilities.
Analogy: Instructions for a driver on how to change a tyre
Software example: Instructions on how to upload a data list to the system
Here are some rules for writing how-to guides:
Some examples of great how-to guides are:
Another type of documentation you may need to use in your knowledge base is an explanation. This type of documentation may not even have its own section, but could be interspersed through the rest of your content. It provides crucial know-what for your users regarding your software.
An explanation is geared towards helping your users understand a particular topic, and providing more background and context. It can provide clarity and illumination for a certain subject, and offer a little more information than you’d expect on a “need-to-know” basis.
Analogy: Article on the design history of a particular car model
Software example: Article on the design process behind the software
Some rules for writing good explanations:
A reference guide is an information-oriented technical document that describes the software, or any related aspect of the software that your user needs to know about.
It could include reference material like a glossary of terms used in your knowledge base, or API and webhooks documentation that includes the main interfaces/properties/methods for your software. You could list technical specifications for your software, current integrations, and so on.
Analogy: A handbook covering the technical specifications of that particular car model
Software example: A glossary of terms used in the Document360 knowledge base
Some rules for writing reference documentation:
Now we’ve covered the different types of documentation you might need, we’ll move on to the overall presentation of language.
A support knowledge base is still part of your overall company brand, and so it should be written in a consistent voice and tone. But first, what are voice and tone?
Voice and tone in writing are two separate but related concepts.
Voice is the personality of your brand, and it is:
Tone is the content-specific current state of mind and emotion for your brand, and it is expressed by:
Voice and tone is ultimately an expression of your brand’s personality, and will be different for every company. The MailChimp style guide is a fantastic resource for anyone looking to create their own voice and tone style guide.
Even better, we’ve compiled some real-life inspirational phrases that will help you start to build your own guide.
Microsoft’s brand voice: Above all, simple and human
Buffer’s voice is: relatable, approachable, genuine, and inclusive
MailChimp’s voice is: Using offbeat humor and a conversational voice, we play with language to bring joy to their work. We prefer the subtle over the noisy, the wry over the farcical. We don’t take ourselves too seriously.
Splunk’s voice and tone: Splunk docs are casual and approachable, yet succinct and direct. Aim to be confident, friendly, and comprehensive, and not insensitive, saccharine, or complicated.
Rackspace voice and tone should: Build trust, inspire confidence, make things easier, develop a relationship with Rackspace users.
Voice and tone can be broken down into more concrete aspects, which you can expand on for your contributors.
Every knowledge base employs its own lexicon, and your choice of terminology must be kept consistent across your help content. Terminology teaches your contributors how to correctly refer to different parts of your software, in keeping with the branding you want to represent to the outside world.
For example, don’t refer to the “widget” at the beginning of an article, only to switch to the “doohickey” later down the line. Consider creating a comprehensive glossary of terms for your writers to refer to.
For example, here is a handy visual example from the Splunk documentation explaining how writers should refer to its software:
Terminology is important to get right because you are teaching your users how to describe your software. It’s often unfamiliar ground that has the potential to confuse users who are new to your product, or who haven’t used your knowledge base much before.
A lack of clarity over terms could lead to a failure to follow instructions, and frustrated and unhappy users. If you have an obvious inclination for what a particular feature should be called, follow your instincts instead of coming up with fancy names. The more obvious the better.
Distinct from your terminology, word choice in your knowledge base refers to the more general words your contributors might choose when writing help content. As with any kind of writing, your language choice strongly influences the meaning that readers take from your writing.
Some factors to take into account in terms of word choice are:
Word choice is an important factor when representing your particular brand, and contributes to your brand’s tone. The overall aim is to make word choices that result in content that is easy to read and unambiguous – so your users can follow your instructions.
Sometimes technical terms are necessary to get your point across, but you should use them carefully. Always assume that your readers may not be familiar with the technical term, and when you do use one, link to a definition.
Similarly, don’t use a complicated word (such as “utilise”) when you could use a simple one (such as “use”). You can use free tools such as Hemingway to check the readability of your content.
Using contractions (“don’t” rather than “do not”) can make your content more readable, but it also makes your content much harder to translate. Therefore, content with contractions is less suitable for international audiences. The same goes if your language is too informal – it’s also harder to read for those with English as a second language.
A SaaS knowledge base is meant to be read online, and it should be written in a way that appeals to web users.
Web users are well-known for scanning content rather than reading, and skimming straight to the parts that are relevant to them. Therefore, you should break your content down as much as possible, and use formatting to highlight the most important parts of your content.
Here are some basic rules for creating scannable web content:
Asking your contributors to write in a scannable format results in better usability for your knowledge base end users.
It’s important to break up your content as much as possible into sections, and write in a topic-based format. This is so your content can be easily scanned, and also reused in other locations.
Knowledge base content should be presented consistently, and there are a number of factors you need to control in your writing. It’s the little things that contribute to the impression of your knowledge base as a professional resource, and which make your content easier to absorb.
For example, using particular styling in a uniform way, which includes:
You also need to standardise the formatting of particular text elements:
Standardisation makes your content easier to read and gives it coherency. It makes your text less ambiguous, and helps users when they are searching for information within your content.
There’s no single right way to format your content. The main concern is to keep formatting consistent within your own content.
You can include as many sections as you like in your style guide. What you end up with depends on the amount of information you need to include for your knowledge base.
If you don’t have much content to release, or you’re short of time, consider creating a one-page style guide that covers only the most important considerations.
At the other end of the scale, you might have a lot to share. For example, you may need to explain how to write for international audiences and how to accommodate a translation strategy. You may need to instruct your writers on how to refer to third parties, how to write content for chatbots, following accessibility guidelines, and so on. In that case, take your time, and split your style guide into as many sections as needed.
Don’t be shy about taking inspiration from some of the biggest brands on how to compile a knowledge base style guide. Keep your eye out for formatting you like the look of. Remember – you’re in good company.