This is the first in a series of suggested practices in creating Knowledge Base content.
Even the best of writers have writer’s block without a list of guidelines to follow when it comes to writing Knowledge Base content. Below are a few tips to keep your content flowing:
- Language
- Customer Context
- Avoid Oversharing
- Be Personable
- Consider your internal audience
- Consider your action words
- Forget the quotes
- Use lists
This post is focused on knowing your audience. Let's do some learning!
Consider your audience: who are you writing for?
Language
Take your audience language into consideration. If the language your company uses is North American English to communicate with customers, use North American English spelling.
Examples of language differences:
- color vs. colour
- behavior vs. behaviour
Customer Context
Make sure to phrase the title using terms for which customers are likely to search rather than the underlying technical problem. Try to be specific. The person searching for the issue may not be the one responsible for solving it.
Avoid oversharing
Give it a once-over to make sure there is no customer-specific information included in the article including:
- User names in the text
- Names in URLs
- Names, users, or URLs in screenshots and attachments
Be personable
Avoid using words like:
- “the customer"
- “the user"
To the customer who would be reading this, it sounds cold. Make the content more relatable. Use the word "you" or rephrase the sentence. Also try to stay away from first person, like “I” or ”we.”
Consider your internal audience
Keep internal company related information out of the article, unless you have a specific internal notes section to place the internal only information, if you think other employees should be aware.
On that same note, make public articles generic and usable for all users.
Consider your action words
When providing instructions it's better to use action words that you or the customer will use.
Example of action words to use:
- "Click" for buttons
- "Press" for keys
People are far more inclined to click or press keys rather than "hit". No keyboards were harmed in the writing of this blog post. You can say "Click Save" or "Press Return".
Looking for more direction on writing directions? Check out Tips for writing Steps to Reproduce and procedures.
Forget the quotes
Quotation marks are not necessary around names of things in the interface that are capitalized or around obvious computer terms.
For example:
- Table names
- System property names
- File names
Use them to set off and represent exact language (either spoken or written) that has come from somebody else.
Use lists
Bullet points help to make what you're saying more clear. Breaking up blocks of text into organized chunks helps the reader understand what you are saying. They put focus on what you want to emphasize.
There are two types of lists:
- Ordered lists
- Unordered lists
Use an ordered list only when the sequence in which some does or reads the list is important. All other lists can use unordered lists.
Bonus* tips to help create content in your knowledge base
To make your content more tidy and legible, here are a few bonus tips:
- Use present tense like “the function is called” instead of future tense “the function will be called."
- Avoid the phrase "the below" - use "the following" instead. For example, instead of "See the below example," say "See the following example."
- If a screenshot directly follows the text, you don't have to give any physical direction at all. Use "as shown in the screenshot" or do not include any introductory text. Say "use" rather than "utilize." "Utilize" means to use something in a way in which it is not intended, for example, "utilize a book as a hammer." Speaking of screenshots, to find out more about screenshots and attachments, check out this blogpost 10 tips to make sure your Attachments and Screenshots are relevant and useful.
Easy enough, right?
5 Comments
