5 Types of Badly Written Knowledge base Articles (with examples)

A knowledge base article is like an apple. A fresh, crisp apple makes a wonderful snack, bakes a delicious pie, and brightens a green salad. But a mushy, flavorless apple makes a dreadful snack, bakes a tasteless pie, and ruins a green salad. 

To improve the dish it’s added to, the apple must be delicious itself. A knowledge base article may be the entire answer to a customer’s question or just one ingredient the technical support agent uses to craft a response to the customer’s question. And just as we cannot use a nasty apple to prepare something good to eat, we cannot rely on badly written KB articles to provide excellent support.

Five common types of badly written KB articles

Every organization faces its own challenges with KB content, but chances are good that you’ve seen these common types of badly written KB articles already—perhaps they even live in your company’s knowledge base?!

1. Marketing messages compete with technical support content.

Whether the KB is customer-facing or internal, the articles shouldn’t contain marketing messages. Marketing messages build excitement about a product or loyalty to a brand; they don’t answer questions or solve problems.

In this hard-to-read KB article, marketing messages interfere with information the customer wants about roaming rates.


What are ABC Mobile’s roaming rates within the Caribbean?

We’ve got great news for our customers! We know you love to travel, and now we’ve got you covered. When you use your ABC Mobile phone when travelling in Caribbean countries, you’ll get the same roaming rates as if you were calling from home.

Call any Caribbean number and pay your local rate only. We’re committed to offering you affordable roaming rates when you’re on the road! This same-as-local roaming rate applies in these countries: Anguilla; Antigua & Barbuda; BVI; Barbados; Cayman Islands; Dominica; Grenada; Jamaica; Montserrat; St Kitts & Nevis; St Lucia; St Vincent & Grenadines; Turks & Caicos & Trinidad & Tobago.

2. Authors add new information without revising the article.

Sure, in a time of rapid change, it’s OK to drop a quick update into a KB article without rewriting the whole thing, but that quick update should have a short shelf life. It’s too much work for any reader to synthesize multiple updates while they read. Avoid presenting geographic layers of information in a KB article, especially if the updates contradict other content in the article!


How do I stop payment on a personal check?

To request a stop payment on a personal check, use Online Banking or call Customer Service at 1.800.888.0000 Monday through Friday from 7 a.m. to 10 p.m.; Saturday and Sunday from 8 a.m. to 5 p.m., local time or by calling the number on your statement.


We’ve extended Customer Service hours of operation to Monday through Friday from 7 a.m. to 11 p.m.; Saturday and Sunday from 8 a.m. to 6 p.m., local time. NOTE: Printed statements still show the former hours of operation.

New info - updated

To request a stop payment via Online Banking, select the account and click Stop payment on a check under Services. Then provide check number, date written, exact amount, and payee. If the amount and check number are not exact, the check may be paid. For more information on stop payments and fees, see attachment: deposit-agreements.pdf.

3. It’s written as a bulleted list when it should be in a table.

We all love bullets, but a bulleted list isn’t the only way to make information easy to read. This KB content would be much better in a table because it could provide a “Feature” column, a “Removed or Retained?” column, and a “How to Update” column. Tables group similar information and make comparisons easy.


Which features will be removed when I upgrade from a previous version of Windows?

  • If you have Windows 7 Home Premium, Windows 7 Professional, Windows 7 Ultimate, Windows 8 Pro with Media Center, or Windows 8.1 Pro with Media Center and you install Windows 10, Windows Media Center will be removed.
  • Watching DVDs will now require separate playback software.
  • Windows 7 desktop gadgets will be removed as part of installing Windows 10.
  • Solitaire, Minesweeper, and Hearts Games that come pre-installed on Windows 7 will be removed as part of installing the Windows 10 upgrade. Microsoft has released a version of Solitaire and Minesweeper called the “Microsoft Solitaire Collection” and “Microsoft Minesweeper.”
  • If you have a USB floppy drive, you will now need to download the latest driver from Windows Update or from the manufacturer's website.
  • If you have Windows Live Essentials installed, the OneDrive application will be removed and replaced with the inbox version of OneDrive.

4. Notes interrupt the instructions.

In this article, the two long notes interrupt the five-step process to getting started with the Photo Fix-Up Tool. The notes make it harder for users who are trying to self-serve and for technical support agents who are trying to help users. Give readers the notes before the list of steps to make the KB article easier to read and the steps easier to follow.


How do I get started with the ABC Photo Fix-Up Tool?

  1. Go to http://PhotoFixUp/Tool
  2. Click Login. NOTE: You can log in with your personal username and password or with the username and password assigned to your corporate account. You will have access to the same account features with either username and password.
  3. Once logged in, click Search Images and provide the file name or image type. NOTE: If you are a first-time user, you will have to accept the Terms and Conditions before searching.
  4. In the search results, click on the image you wish to edit.
  5. To enlarge the image for editing, use the scroll wheel or Ctrl+

Best Practices for Knowledge Base Writing

Watch CX writing guru Leslie O'Flahavan (E-WRITE) and Sr. Technical Writer Clint Rodenfels in our on-demand video as they you show how to write the best Knowledge Base articles.

5. The title of the KB article and the content don’t match.

The title of this KB article implies the article will list the steps customers should take if they receive a hold on their account, but the article itself explains what a hold is. Huh? Why did this disconnect happen? It could just be poor KB hygiene, but it’s probably the SME’s sense that the answer to “What should I do?” is obvious. (If customers can be shown what a hold is, they’ll know what to do when a hold is placed on their account.) No matter why the title and article content don’t match, the disconnect does a lot of harm. It means the wrong info turns up when users search, and confusion occurs when they read!


What should I do if I receive a hold on my account after I have made a deposit?

A hold means that we've received your check for deposit, but you won't be able to use the funds until the hold period has expired. Holds are placed to help protect both you and us from losses that could occur when a deposited item is returned unpaid.

Hold periods are typically 2 to 5 business days, and may extend longer in unusual circumstances. If the deposited item is returned unpaid before the hold expires, those funds will not be made available to you. If the deposited item is returned after the hold expired, we charge your account for the amount of the item.

We use many factors to determine if a deposit hold will be placed, including your account history, account balances, the maker, the dollar amount and type of check being deposited.

The five types of hurt caused by badly written KB articles

  • Information distrust. When articles are difficult to read and understand, customers and support agents alike begin to distrust the KB. They start to think, “Well, yes, the answer is probably in the KB, but I doubt it’s up-to-date, readable, customer-centric…” etc. Information trust is difficult to win, and information distrust is extremely difficult to overcome.
  • Unwillingness to use self-service. Customers aren’t particularly hardy when it comes to badly written KB articles. They do not think, “Well, this one KB article is confusing. I bet the others are clear.” When they struggle to understand a KB article, they’re likely to give up on that type of self-service and on other types too, like a mobile app or a chatbot. When they try to help themselves and fail, their desire to have your technical support team hand-hold them just grows.
  • Personal stashes of un-reviewed information. When technical support agents can’t rely on KB articles, they create stashes of copy-and-paste content they’ve written themselves. That’s not good. Managers can’t know whether these DIY articles are well-written and accurate. If they are, they should be shared. If they’re not well written, they shouldn’t be used.
  • Wrong answers. While a badly written KB article might actually contain the right answer, the extreme effort required to understand means many people will miss it. Customers are likely to misunderstand a badly written KB article, and technical support agents end up giving out incorrect info when the KB article is too hard to read.
  • Higher contact volume and longer support conversations. Badly written KB articles cause more contacts from customers. Some will want service do-overs because their self-service efforts failed. Some customers will contact us about the bad experience with the KB and also about the question or complaint that drove them to the KB in the first place. Our support conversations will take longer because our customers are frustrated, confused, or—perversely—more certain that they’re right about something when they’re not.

If your knowledge base has bad apples—poorly written articles—in it, please don’t be discouraged. Each writing problem I’ve listed is fixable! Start by doing a quick audit of the most frequently used KB articles. With a little effort, a red pencil, and a commitment to providing readable content, you can improve your KB articles, so they truly provide support.

This is a guest post written by Leslie O’Flahavan of E-write. Find her on Twitter or connect on LinkedIn.

Share article:

More interesting articles