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 four 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 a three ways to write a great title for a knowledge base article:• User question: How do I Set Up VPN on Linux?
   • Gerund phrase: Setting Up VPN on Linux
   • Adverbial phrase: How to Set Up VPN on 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.

2. Use headings and lists to make the 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.

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.

4. Number the steps if they must be completed in a sequence. Many knowledge base articles explain how to do something. When the 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.

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.