Creating a (Good) Knowledge Base Article

Knowledge base (KB) articles are an important part of TechConnect. Because we work with tech daily and probably have for years, we often forget what it is like to be a typical user. We may not realize that what is simple for us to understand may not be for them.

Best Practices

  1. When writing a KB, consider that you could be writing for someone:
    1. of any age
    2. of any educational background
    3. who rarely uses technology in their daily job
    4. who is a second-language English speaker
  2. Write at an eighth-grade level. It is literally a thing. Here's a quote from Readability Formulas that explains it: Writing at an 8th-grade reading level is a proven way to capture every type of reader without bias. It’s significant for non-native English speakers, too. Using simpler language and clear explanations helps to overcome learning and language barriers; we make our content more inclusive and comprehensible.
    Not sure what level you are writing at?  The Hemingway website tells you the level at which you are writing. And, in case you are wondering, this is written at a 6th-grade level. 
  3. Try to write in active voice instead of passive voice. (Active Versus Passive Voice - Purdue University)
  4. Keep it simple and short; the fewer words you can use to describe something, the better.
  5. Check step-by-step instructions during your review process. Even if the look of a dialog box changes, it needs to be updated in the KB.
  6. When using acronyms, define them the first time. (example: Virtual Private Network (VPN))
  7. Don't assume the user knows technology or abbreviations. If you are talking about the VPN, put in a brief sentence describing what it is.
  8. Pay attention whether you "click" an option or "choose" or. "select" an option - they are different. And never tell someone to hit a key.
Most importantly, ask yourself if this KB is really necessary and helpful to our users. If what you are writing affects 1 out of 500 users, do we really need it? Consider that it might be better to put it in the For ITS Use category as info for ITS if anyone ever contacts us about it.

An Example of a Well-Written KB

Sometimes, it is just easier to see something than read about it, so here is an example of a good KB (but you still have to read a little):

Visual example of a good article

Other examples of good KBs (note that they don't all need photos):

GOOD NEWS: You don't have to take images as long as I can follow the instructions and get the images. This is to make sure our KB images have a uniform look. You must take images if I can't follow the instructions because I can't access a system. Please make sure they are clear and easy to read at a width of 600 pixels.

Determine Where the Article Will Be Stored
All About Headings
TechConnect Style Specifics

Communications and Marketing has a brand style guide. But here is a style guide specifically for TechConnect:

  • Don't use UTHSC per the Chancellor - use UT Health Science Center unless it sounds awkward, like in the case of NetID or email. In those cases, use UT NetID or UT email.
  • Article titles shouldn't start with "How to..." to help users find articles more easily. They should be descriptive of the type of instructions they contain and easy for the user to find - Zoom, Microsoft, Outlook, etc.  
    • Don't use "How to Download Zoom."
    • Use "Downloading Zoom" or if there are a lot of Zoom articles a main category, use something like "Zoom: How to Download."
  • For instructions with content like "Click Submit," it should read Click Submit, not Click "Submit" or Click Submit. The action should be bolded.
  • Don't add your name to a TechConnect Article (when it is published, your name appears on the right with other information about the article)
    showing where creator name appears in TechConnect articles
  • Don't use italics (per C&M's Quick Style Guide for Writers). Use quotes if referring to a book or article that isn't linked.
  • Numbers: Spell out below 10; use numerals for 10 and greater except when they begin a sentence.
  • Don't use periods after am and pm (and don't capitalize per C&M).
  • Phone numbers are always written with periods, not dashes (901.448.2222).
What are Shortcuts?
Can AI Help Me?

Yes, yes, it can. 

AI might not be able to write the instructions for you, but it can give you a good start.  

For example, you can go to UT Verse and ask it to create instructions with bullet points on how to set your auto-reply in Outlook for Windows.

Look what it gave me:

Instructions generated by AI through UT Verse

You cannot take this and just drop it in a KB without going through it and verifying its accuracy, but it is a great start!

Print Article


Article ID: 151352
Tue 5/14/24 7:48 AM
Wed 6/5/24 4:02 PM