Introduction
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
Section 1 – Tutorials
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:
Starting off your tutorial
- Include a summary of what the article contains at the beginning of your tutorial
- Tell your user what they can expect to learn, and what they prerequisites they will need to complete the tutorial
- Focus on offering a way to get your user started with the software
Formatting your tutorial in steps
- Try to arrange the necessary steps in progressive order of difficulty, from easy to hard.
- Include only the steps your user needs to take to complete the task
Include only concrete steps in your tutorial, and avoid abstract concepts that don’t relate to practical learning. - Control the length of your tutorial steps – keep them concise but not abrupt.
Creating a working tutorial
- Affirm that you have created a working tutorial, including checking that it operates in different environments.
- Provide a working example for your tutorial so the user can learn by doing
- Include user-visible results throughout the tutorial that provide feedback on the task.
- Test that your tutorial is repeatable for your users
Tutorial style
- Include only the bare minimum amount of explanation needed to complete the task
- Don’t make your tutorials too long or complicated
- Don’t link to external sites during the tutorial – keep your users focused on the task at hand
- Include “next steps” or further reading at the end of your tutorial for users who want to learn more
Some examples of great tutorials are:
Section 2 – How-to Guides
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:
Starting off your how-to guide
- Choose a descriptive name for your guide that tells the user exactly what the guide intends to solve
- Format your how-to guide as a list of ordered steps (1, 2, 3)
Summarise the solution at the beginning of the guide so more experienced users can skip to the important part - Focus on the results of achieving a practical goal with your software, and solve a specific problem that has been troubling the user
Writing procedures
- Format your procedures consistently in every guide so your users can scan the content
- Restrict your procedures to fewer than seven steps to avoid information overload
- Describe the place in the UI where the action takes place before you issue an instruction
- Include actions in each step that finalise the step; for example, select “OK”
- Use generic input words that correspond with any device the user might be using; for example, avoid click or swipe in favour of open or select
- You can shorten simple sequences using right angle brackets; for example Select Accounts > Other accounts > Add new account
Style and format
- Write your guide in full sentences with proper grammar and punctuation
- Include call-outs within the body text to highlight necessary information – for example, how performing a particular action will affect the system
- Avoid explaining “conceptual information” by linking to explanations elsewhere instead
- Leave out any information that is unnecessary for completing the task
Some examples of great how-to guides are:
Section 3 – Explanation
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:
- Provide as much context as you need to and explain the “why”
- Don’t instruct the user or include any technical reference
- Use this type of content to expand user understanding of the software as a whole
- Use simple language that anyone can understand
Section 4 – Reference
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:
- Aim for consistency in your structure, tone, and format
- Describe only the relevant technical component, and avoid instructing or explaining
- Use a straightforward and matter-of-fact tone
- Check rigorously for accuracy
Section 5 – Voice & Tone
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:
- Consistent across different types of content
- The words you use or omit in your writing
- The common turns of phrase you employ
- The way you write a sentence
- Use of punctuation to create a particular expression
Tone is the content-specific current state of mind and emotion for your brand, and it is expressed by:
- Word choice
- Punctuation
- Emojis
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.
For example:
- Write to the user using the second person and use the imperative mood
- Use the active voice to make the performer of the action the subject of the sentence
- Use present tense
- Write in confident language
- Make suggestions rather than give commands (“you can do X” rather than “you must do X”)
- Use helpful words and phrases that are informative, easy to understand, and clear
- Avoid laying the blame for any negative situation on the user
Section 6 – Terminology
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.
Section 7 – Word Choice
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:
- Use of contractions (“don’t” instead of “do not”)
- Choose the simplest words (“use” rather than “utilise”)
- Use short sentences with only one or two clauses
- Avoid ambiguous terms
- Remove jargon and go light on technical terms
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.
Section 8 – Scannable Content
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:
- Present the most important content at the beginning of your article (“above the fold”)
- Include a navigation element or table of contents at the beginning of long content
- You can include a short summary of the solution at the beginning of your how-to guide so more experienced users don’t have to read the whole article
- Write your content in short headings, sentences, and paragraphs
Front-load your headings so that the most important keywords are near the beginning - Use bold formatting to highlight key words or phrases
- Use call-outs to highlight warnings or other important chunks of information
- Use ordered or unordered lists for sequences of information; ie any kind of procedure
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.
Section 9 – Standardise your Formatting
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:
- Fonts
- Colours
- Capitalisation (includes use of sentence case or title case)
- Emphasis (using bold)
- Italics
You also need to standardise the formatting of particular text elements:
- URLs
- Headings
- Naming UI elements
- Code snippets
- File names
- Numerals or words
- Date and time
- Abbreviations
- Product names
- Tables
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.
Final remarks
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.
–