When I was first learning how to write in elementary school, my teacher would give us strips of colored paper so we could understand the difference between an introductory sentence, a body sentence, and a thesis statement.
There was a proper order in which to write a paragraph. As I learned more, I hated being restricted in my structure and grammatical rules. How dare they take away my creativity!
Now that I've done a variety of different writing — from journalism to technical writing to creative writing — I’ve realized that all writing requires a certain structure. Having a designated structure makes it easier for your readers to follow your writing.
I hate to say it, but I'd be lying if I didn't tell you the truth — there is a right and wrong way to write your knowledge base articles.
Luckily, as I've worked for ScreenSteps (a knowledge base company), I've been gathering the best tips for writing knowledge base articles.
If you want your knowledge base to help your employees do their jobs with fewer mistakes, here are 11 best practices that you'll want to incorporate when writing your knowledge base articles.
1. Understand the purpose of the article before you write it
Know who is going to use your knowledge base article and when they will be using it. This will change how you write the article and design it.
For example, if your call center agent simply needs to schedule an appointment for one of your dental offices, they can pull up a reference guide listing the addresses. They don’t need a step-by-step guide to find the right address. A table will suffice.
Remember: The purpose of your knowledge base articles is to help your employees get unstuck. Focus on including the information — no more and no less — that helps your employees get out of a situation where they don’t know what to do.
2. Write your titles the way employees ask the questions
What questions are your employees and customers asking? Those questions should be your knowledge base article titles.
Often, company leaders attempt to organize procedures by titling them with complicated internal jargon or number codes. The problem is it makes your customers and employees pause in their search.
Essentially, your employees have to translate their questions into corporate wording before they can search for and find the answers they need. By titling your knowledge base articles as the questions are asked, it makes it easier for employees to find the articles they need.
3. Don’t use if-then statements
When you rely on if-then statements to help your employees make decisions, it adds a lot of text to a page. That can be overwhelming for the reader. Your employees need to read more instructions. It becomes difficult to identify the choices and follow the procedure.
Replace if/then statements with decision trees. Your decision trees are multiple-choice questions where the answers lead your employees to their next step. This allows for shorter questions and a list of answers that are easy to skim and select the next step.
4. Format the article so it is easy to follow
There are a variety of different types of knowledge base articles. This means you can present your information in different ways depending on the purpose of the document.
For example, you don’t need to write a standard article with detailed explanations when an employee just needs a quick reminder. Instead, provide a checklist.
Note: Often knowledge base software companies provide templates for different types of articles. Check your knowledge base for premade templates.
🎥 Watch Related: Why How You Design Your Knowledge Base Articles Matters
5. Write short and choppy sentences
Don’t write complex sentences that require multiple commas and an advanced reading level to read. Your employees want the cliff notes version of the story when they are in the middle of a procedure.
Keep your sentences short and choppy. No, you won’t win a Pulitzer prize for writing, but you will help your employees with their jobs.
Remember: Your employees will be using your knowledge base resources while they are doing a task, which means they are multitasking as they are reading your guides. Complex sentences with advanced grammar take a reader’s full attention. A knowledge base article is not the right place for that.
6. Include screenshots
Don’t rely ONLY on text to provide instructions. When you include screenshots in your procedures, you show your employees what to do on top of telling them what to do.
Readers LOVE screenshots. It is extra helpful if you can annotate your screenshots so that your end-user knows exactly what to click or where to look on a screen.
A word of caution: There’s a nice balance between too many and not enough. The goal is to simplify procedures, not overcrowd them with words or images.
7. Include design elements
Once again, words aren’t the only way to communicate a step-by-step procedure. Use your authoring tools in your knowledge base to write clear help guides.
Every knowledge base software has different authoring tools. Some common tools include:
- Bolding or italics
- Text color
- Highlighting
- Bullets
- Indentations
- Foldable or expandable sections
8. Link to additional information
You don’t want to give them the story from the creation of the policy to how it evolved to what it is today. Provide links so employees can access more information or connect procedures.
For example, in a call center, your intake script is a different procedure than your troubleshooting guides. Once your employee has discovered the purpose of the call, they open up a new procedure that is linked in your intake script.
Using links provides employees quick access to additional information and procedures they need to complete a task.
9. Don’t have long standard operating procedures
How long should your standard operating procedures (SOPs) be? The short answer is it is as long as it takes to answer a specific question or perform a procedure.
That doesn’t mean that you pile multiple procedures with all the possible outcomes into one procedure. Your SOPs should not be manuals.
If you have long SOPs with multiple off-shoots, break them into smaller guides that only cover one procedure.
🎥 Watch Related: Knowledge Base Tip: Format Articles to Support New & Tenured Employees
10. Optimize your articles for search
Writing a knowledge base article goes beyond the text in a help guide. Creating a knowledge base article includes optimizing the article so it is easy for your readers to search and find the guides they need.
Optimizing your articles includes writing clear titles, using keywords, and more. Most knowledge base software services offer tagging for additional keywords. Add related or alternate keywords employees use to articles.
11. Test your procedures
Before releasing your knowledge base articles to your entire organization, take them for a test ride. Select employees and have them test the procedures out.
Watch your employees use these guides. Is there a place where they are getting stuck? Are they adding in any additional steps? What is missing? Were they confused at any point?
Take these observations as well as your employees’ feedback to make updates to your knowledge base articles before publishing them.
Create articles that support employees at each step of the process
Writing knowledge base articles can take a lot of time and effort. Sometimes it’s tempting to simply get something written down so that documentation exists, but that often leads to employees not being able to use those guides you spent so much time writing.
When you have a knowledge base with the right authoring tools, you can create guides your employees can rely on.
ScreenSteps’ authoring tools are simple yet powerful. You can write knowledge base articles in minutes, depending on the complexity. From checklists to workflow articles, you can write a variety of help guides. One company created 4X the documentation in ¼ of the time when they switched to ScreenSteps.
Need more tips for writing SOPs? Follow this six-step process to write SOPs that are easy for employees to follow while in the workflow.
