Maintaining a knowledge base full of well written articles is as difficult as keeping a preschool playroom tidy. Here’s why.
Some KB articles are created to meet an emergency need, and they’re hurriedly, even poorly, written from the day they’re published. Other KB articles start out fine, but frequent updates make them long and difficult to read. And some suffer from a lack of proofreading or were written by a person who’s not so sure whether the right spelling is “receive” or “recieve.”
If your knowledge base contains badly written articles (and whose doesn’t?), don’t despair. You can fix these articles, and you should. Because KB articles are reused and revisited so often, you always gain results when you invest your writing efforts in improving content quality. Plus, fixing a bad KB article isn’t that hard. Here are four manageable ways to revise a badly written KB article. (Don’t worry! Most articles don’t require all four fixes.)
1. Give the Article a Full Title, Not Just a Topic
Users read the title to confirm they’ve found the article they need. Users always read the title before they read the article. Always. If they’ve searched on a term, they’ll be presented with several KB article titles in the search results, so the titles need to contain enough information to help them choose the right article to read.
Here are three ways to write a great title for a knowledge base article:
- User question: How do I Set Up a VPN in Linux?
- Gerund phrase: Setting Up a VPN in Linux
- Noun phrase: How to Set Up a VPN in Linux
Don’t write simple topic titles for your KB articles. They’re not specific enough to help the user confirm whether they’ve found what they need or to help the search engine offer up the best options.
| Original Title |
Improved Title |
| Web Conference Host Key |
How to Use the Web Conference Host Key
|
| A request form to transfer to another department |
Which request form must I complete to transfer to another department?
|
| Non-operational Facilities |
Eliminating Non-operational Facilities from Leasing Inventory by December 2020 |
2. Use Headings and Lists to Make Content Scannable
Whether your KB is internal or customer-facing, most users don’t want to actually read each article; they want to scan the article quickly to find the information they need. However, they can’t scan if the article lacks scannable features like headings and lists, which enable users to see the article’s topics and subtopics at a glance.
Here’s an article from the City of Highland’s public-facing knowledge base. While it’s not very long, it is nearly impossible to scan. Several types of information are jammed together in one paragraph. The improved version helps the user see the sections of the article and scan over to the part they need to read.
| Original Article |
Improved Article |
|
What are the building permit fees?
Permit fees are based on the estimated cost of the project (including all material and labor costs). Permits are $25.26 for each $1,000 of estimated cost with an additional fee of $25.00 for a Certificate of Occupancy/Approval as required. If appropriate to your project, the Department of Inspection also collects fees for Zoning, Fire Marshal and Water Pollution Control regarding your permit application. Some of these other departmental fees are variable, therefore, please call the Department of Inspection at 111-222-3333 to determine the exact fees for your project. Please pay for your permit using check or money order made out to the City of Highland in the exact amount of your permit fee.
|
What are the building permit fees?
Permit fees are based on the estimated cost of the project (including all material and labor costs). Some of permit fees are variable, so please call the Department of Inspection at 111-222-3333 to determine whether you will also need to pay Zoning, Fire Marshal and Water Pollution Control fees for your permit application.
Permit fees
- The permit fee is $25.26 for each $1,000 of estimated cost.
- The Certificate of Occupancy/Approval fee is $25.00, as required.
How to pay permit fees
- Make a check or money order out to the City of Highland in the exact amount of your permit fee.
|
3. Make it Easy for Users to Take Action.
If the KB article mentions what the user should do, the article should provide the information that makes that action possible, such as a hyperlink, phone number, email address, download, etc.
The original version of this City of Highland KB article positively flatlines by telling users who want to report a building code violation that they can inform the Code Enforcement Division but omitting any of the ways to do just that. So frustrating! The improved version helps the user do what they need to do.
| Original Article |
Improved Article |
|
How do I report a code violation?
You may create a Service Request, call or email the Code Enforcement Division with the address of the concerned property along with any details of your complaint.
|
How do I report a code violation?
You may create a Service Request or contact the Code Enforcement Division at 111-222-3334 or BuildingCode@HighlandCity.gov to provide the address of the concerned property along with the details of your complaint.
|
4. Number the Steps if they Must be Completed in Sequence
Many knowledge base articles explain how to do something. When the user must complete the steps in order, those steps should be numbered, not bulleted.
Here’s an article from a large school district’s internal KB. When the steps are numbered, it’s easier for the user to know where they are in the process or to take the process up again if they get interrupted in the middle. The original version had four bulky bullet points. The improved version has seven clear, streamlined steps.
| Original Article |
Improved Article |
How to edit a Travel Authorization
- First, you must be logged into PeopleSoft Financials online, and then navigate to the correct page (the link called Travel and Expense Center).
- Next, you must click the correct link to open the Travel Authorization form. Then click the link called Modify.
- Once you have the form open on your screen, you can pick up where you left off or just make the changes you want to make to it. Always remember to click the Check for Errors button after you make each change on an item. This not only checks your work for you, it also saves the changes you make.
- When you're finished you can either save it for later, or submit it right then and there.
|
How to edit a Travel Authorization
- Log in to PeopleSoft Financials.
- Go to the Travel and Expense Center.
- Click the Travel Authorization form.
- Click Modify.
- Edit or complete the Travel Authorization form.
- Click the Check for Errors button after you make each change on an item. This will check your work and save your changes.
- Click Save for Later if you want to finished editing at another time or Submit if your edits are complete.
|
Please Don’t be Discouraged
Maybe a lot of your KB articles look like the “original” versions presented here. Maybe you’re feeling a bit overwhelmed about how much fixing you need to do! Take heart. If you focus your rewriting efforts on the most frequently used knowledge base articles, each edit you make will help a lot of users. Improving your KB articles is never wasted effort. Better articles make life easier for users and for you, too.
Read Part 1 here: Five Types of Badly Written Knowledge Base Articles (with examples)
