We use style guides in our day-to-day lives. You may not have noticed because it is such a natural part of communication. No matter which industry you work in, writers use a certain set of written rules.
Think about it. How do you read a book? From left to right. How is a book organized? Into chapters. Or, what comes first when you write an email or handwritten note (yes, those archaic things)? A salutation and name.
There are certain written rules we live by in society. These rules make it easy to find the information we need quickly. If we need to know who wrote the letter, we check the signature at the bottom. These rules of communication simplify our lives.
As a former journalist happily subscribing to the AP Styleguide, I appreciate the power of having clearly defined rules for communicating.
Now, as the Content Marketing Manager at ScreenSteps (a knowledge base software company), I see how essential having a knowledge base style guide is for communicating policies, processes, and procedures to your employees.
In this article, I’ll explain why you need a style guide in order to write clearer knowledge base articles. Then I’ll provide five elements you’ll want to standardize in your knowledge base style guide.
Why do you need a knowledge base style guide?
Having a style guide helps you and your team create consistent-looking learning materials.
If your style guide isn’t consistent, then your employees need to learn how to read a new guide every time they open a policy or procedure written by a different content author.
Consider: When Employee A writes procedures, the guides look one way. When Employee B writes procedures, the guides look another way. Then, Employee C is confused about how to read and follow instructions because it is different depending on whether Employee A or B wrote the guide.
Purpose of a knowledge base style guide
There are multiple goals of a knowledge base style guide. Most importantly, it is to create procedures and learning materials that are:
- Concise
- Clear
- Easy to find via search
- Visually logical and easy to follow
A style guide is helpful to both your content authors and your readers.
This is important for authors because it can guide them into creating great learning materials and procedures that are effective at helping employees perform and learn.
This is important for readers because they get a consistent experience each time they read a procedure and they can adopt new procedures and update old procedures in less time.
5 elements to outline in your knowledge base style guide
What information should you include in your knowledge base style guide? You’ll want to include information on how to handle writing and presenting different aspects of your articles. Here are some elements to consider including:
1. Procedure titles
What format do you use for saving your procedures? You want your employees to be able to quickly and easily find your procedures.
Best practices
When you write an article, it can be tempting to create a title that uses technical vernacular. Instead, you want to use terminology that is natural for your employees or customers.
Answer a specific question. Include, “How to…,” at the beginning of the title. Then capitalize the first word and proper nouns.
For example, instead of titling an article, “Purchase orders,” title the article, “How to update a purchase order” or “How to process a purchase order.”
2. Copy of an article
How will the written portion of your procedures look like? How long should your articles be? There are many elements of writing guides to consider.
Grammar
In elementary school, we learn the power of grammar. A comma changes the meaning of a sentence like, “Come eat kids!” to the proper “Come eat, kids!”
In procedures, grammar decisions can help your employees save time by skimming. Think about how you will use:
- Contractions
- Punctuation
- Capitalization
Tip: It can help to ignore traditional grammar rules. Instead use a more relaxed, casual tone where you leave out articles. It makes it easier for the reader to skim. Be succinct. For example, do not say, “Click on the button.” Say “Click button.”
General terms
Standardize your terms and phrases. These are words you want everyone to be able to recognize and understand as they are reading through a policy, process, or procedure.
Provide a glossary of terms in your style guide. Give a simple definition for each term that helps everyone understand when and how these terms should be used.
List of terms to use (e.g. Account, Lead, name of the product, name of the process). Come up with a list of what is the standard wording you will use.
For example, what action words will you use? These are the terms that drive your employees to take action. Select/de-select, check/uncheck, click, press, etc.
Consider which alternative terms people may be using. Use those words to help in search results.
3. Article format
Outside of word instructions, how you present your procedures help different words and sections jump from a page. Standardize your procedure formatting. Decide and provide instructions for when to use these different design elements:
- Bolding
- Quotation marks
- Headings (size, color, font)
- Numbers and bullets
- Spacing
When to use different article types
Some knowledge base software companies offer templates for different types of articles. Set criteria for when you will use those different templates or elements. Those different types of articles could include:
- Checklists
- Workflow articles
- Step-by-step instructions
Best practices
When formatting your knowledge base articles, a few best practices are:
- Include a brief overview/use case to give the procedure context
- Include headings to break up the different sections
- Capitalize the first letter of the heading and capitalize proper nouns
- Start headings with an action verb
- Briefly go through the process
- Bold buttons or fields
- Use lists to identify a series of steps
4. Images
Besides written descriptions, you need to decide if and/or where you will use images in your guides. There are a few options for images. Then you need to decide how you will present these images in your procedures.
Screenshots
Screenshots are powerful in showing exactly what an employee needs to do on a computer. Include screenshots to communicate where to click on the screen.
If you decide to use screenshots, you’ll want to formalize how you present screenshots. What size should screenshots be? Should they be annotated?
Images
With images — whether that is a picture or graphic — you need to decide on a few design elements.
What size of images will you use? Should the images have a border around them? If so, what color should they use? Then determine where on the page images should be positioned (centered or justified to the left/right).
Image Annotations
When there are a lot of details on a screenshot or image, it can be difficult for the reader to know exactly what they are looking at. Adding annotations to images helps direct the reader’s eye.
If you use annotations, make them uniform. Use arrows and circles to point to actions. Or add text to the image to clarify actions. Come up with a standard color for each of these elements.
5. Additional information
How will you present detailed information that isn’t part of the main procedure?
Depending on which knowledge base software your company chooses, you will have a variety of different tools to provide additional information within a guide. This information can help clarify a procedure without crowding the guide.
Some examples of tools that help provide additional information without overcrowding your guides include:
Tables
Tables are a good way to share a lot of information in a smaller space. Often tables are used in situations where there are options according to different variables.
Tip boxes
Use tips boxes to make important information stand out. Essentially, a tip box highlights a “Don’t miss me” message. It makes that information pop on a page so that someone skimming the article won’t miss it.
Foldable sections
Use foldable sections to provide additional information that is relevant but not required.
For example, maybe most of your employees understand how to exchange an internet router. But some employees get stuck on if a customer wants to upgrade their router instead of just exchanging it. Those employees could click a foldable section to expand for more detailed instructions.
But how and when are you going to use those in your company? How much information will you include in a foldable section? When do you need to create a separate procedure (aka: there is too much information for a foldable section)?
Links
Decide when you can add links. Which situations call for linking out to another article in your knowledge base? Which sites are your content authors linked out to?
Tip: You can create articles specific to actions and procedures. And create articles specific to explaining background and concepts. You can hyperlink between the two types so that you don’t overwhelm your employees with unnecessary (though helpful) information.
What knowledge base articles should you write first?
A knowledge base style guide makes it easier for both content writers and readers to communicate. When articles are written using a style guide, employees know what to expect and can easily follow the guides.
After you’ve created your knowledge base style guide, it’s time to get started writing policies and procedures.
With ScreenSteps, you can write and share your knowledge base style guide within our knowledge base. Plus, you can save article templates to make it easier to write content faster. With clearly written procedures in ScreenSteps, companies have increased productivity.
Having a difficult time deciding which procedures to write? Download this brainstorming worksheet to figure out which articles to write for your knowledge base first.
