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. 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.

Unless a step is particularly complicated, we don't need images.

Determine Where the Article Will Be Stored
All About Headings

Heading titles can be found under the Normal dropdown in the toolbar.

Using headings properly is essential for accessibility.

  • The first title is an H1. A page can only have one H1 title, which is entered when creating the name of the article.
  • The next title within the article should be H2 (this makes the font larger and puts a line underneath the title).
  • The next title that relates to the previous is H3. If it doesn't relate to the previous title but is a new subject within the article, use H2 again.

Here's where you choose the Heading:

Where you choose a heading

DO NOT BOLD, ITALICIZE, OR UNDERLINE NESTED TITLES.

DO NOT CHANGE THE FONT OR SIZE OF THE TEXT.

Spelling

Just to keep things consistent, we have preferred spelling for certain IT terms:

  • NetID - instead of Net ID
  • Email - instead of e-mail
  • WiFi - instead of wifi or WI-FI
  • username - instead of user name
  • Website and webpage (no spaces or dashes between words)
TechConnect Style Specifics

Communications and Marketing has a brand style guide.

But here is a style guide specifically for TechConnect:

  • 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 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 numbers one through nine; 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?
Print Article