Writing a knowledge base is hard enough already. So I apologize for what I’m about to do in this post. I’m going to tell you that it’s not just about the ideas in your knowledge base, it’s also about how you present them.
See, beyond those ideas, you need to ensure that you’re always:
- Using the proper tone
- Consistently formatting everything the same
Which, for reasons I’ll elucidate in the next section, is actually surprisingly difficult. That’s where a knowledge base style guide comes into play.
Why Your Knowledge Base Might be a Mess of Different Styles
Don’t worry too much if your knowledge base is a jumble of different styles. It happens to a ton of companies, usually for one of two reasons (or sometimes both!).
First, if you’re part of a team, you might have different people writing support docs. So if:
- Jim writes Article A
- Sally writes Article B
Those articles are probably going to have wildly different styles and formatting…unless you have a pre-defined style guide in place.
Now, if you’re not part of a team, you’re probably saying, “I’m a lone wolf – I’m writing everything myself. So I don’t need to put anything down on paper – it’s all me!”
And that might be the case…if you wrote all of your knowledge base articles in one sitting.
But we both know that’s not how things usually work, right? You probably wrote a heap of knowledge base articles when you first released your product.
But then, three months down the line, you release a new feature. Now you have to write the knowledge base entry for that new feature and…human memories are not that good. There’s a good chance you end up doing something differently, even if you’re not trying to.
So whether you’re solo or part of a team, it pays to put your knowledge base style guide down on paper.
Do Companies Actually Do This? Is a Knowledge Base Style Guide a Real Thing?
Ok, I’m going to tell you how to create your style guide in a second. But first, I want to lead with some examples of companies who are actually doing this. This accomplishes two goals:
- It shows you that I’m not just making things up to create more blog content ?
- It gives you a real-life example you can pull from for your own style guide.
Let’s look at Mozilla first. Mozilla has a whole entry on the style guide for their knowledge base. Because Mozilla is open source, it’s especially essential for them to have a style guide to, in their own words, “make the Firefox support Knowledge Base consistent, resulting in a knowledge base, that is easy to read and contribute to.”. Easy to read? That sounds like a good goal for your knowledge base, right?
The guide goes deep, taking you through everything from capitalization, to whitespace, to serial commas.
Next up, MailChimp’s Voice & Tone is another worthwhile read. While it’s not 100% focused on knowledge bases, it does have a number of entries for both knowledge base and tutorial content:
Whereas Mozilla’s style guide is more focused on style and formatting, MailChimp opts to focus more on, well, voice and tone, than nitty-gritty formatting.
How to Create a Style Guide for Your Knowledge Base
I tossed a couple examples at you, but I have yet to give you a process for actually creating your own knowledge base style guide. So let’s fix that!
Use a Consistent Person
Have you ever read an article where the author switched back and forth between “I” and “We”? I have, and we can tell you that it’s exceedingly confusing.
So, if you’re going to use the first person – pick one and be consistent about it. Even if you’re solo, you can still opt to use “we”. Up to you! Just use the same one.
Additionally, you don’t even need to use first person. You can opt to eschew “I” and “we” altogether.
There’s not really a right answer here – it’s just about consistency.
Standardize Your Formatting
If you read our ultimate knowledge base article template guide, you know that good knowledge bases use lots of instructions with small steps. And those instructions will, at some point, include language like:
Click on File.
So – is it:
- Click on File
- Click on “File”
- Click on File
And when you actually write your lists, is it:
- Step 1: Click this
- Step 2: Click that
Or is it like this:
- Click this
- Click that
Again – you can pick the one you like best – but whichever one you choose, use it consistently across your whole knowledge base.
There are other formatting choices you need to make as well – the Mozilla style guide gives you a good idea of everything to cover, but here are some starter ideas:
- Heading capitalization – will you use sentence case or Title Case?
- Numbers – is it 10 or ten?
- Abbreviations – don’t or do not?
- Acronyms – CDN or content delivery network?
If you’re using one of our knowledge base WordPress themes or plugins, our built-in shortcodes and formatting options can help you stay consistent when it comes to formatting
Get the Voice Right
Finally, you need to go beyond formatting and standardize your voice.
Are you your customer’s friend? Or are you Spock from Star Trek, dispassionately dispensing cold hard wisdom?
Within reason, either is fine. As long as it’s consistent.
In general, you should make sure to follow MailChimp’s knowledge base guide tips. I suggest them not only because MailChimp actually published their guide, but also because I think MailChimp has one of the best knowledge bases out there.
Their advice is this:
- Always make your first priority to answer questions and inform your readers. Jokes are ok sometimes, but not if they distract from that essential goal.
- Avoid speaking like a marketer – you’re just trying to help.
Where to Store Your Style Guide?
You shouldn’t just make these decisions. You also need to actually, you know, write them down in a safe place.
Personally, most of the style guides that I work with are Google Docs documents. That way, you can easily share your style guide and access it from different computers.
But if you prefer another method, go with what you’re familiar with. The only really important thing is this:
You have a copy of your knowledge base style guide stored in a safe place where you, or others, can access it when you need a refresher on how to format your knowledge base.
So, get it down on paper and start creating more consistent knowledge base articles!
The post Get Organized! How to Create a Knowledge Base Style Guide appeared first on HeroThemes.