Creating a (Good) Knowledge Base Article

Body

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

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
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.
Try to write in active voice instead of passive voice. (Active Versus Passive Voice - Purdue University)
Keep it simple and short; the fewer words you can use to describe something, the better.
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.
When using acronyms, define them the first time. (example: Virtual Private Network (VPN))
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.
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

By default, the article will be set to publish in the category you were in when you clicked New Article.

If you need to change that, look at the top section under Category.
Click the X in the existing category to remove it.
Begin typing the name of the category, and it will display the results. Click the one you want.
If you are not sure of the best category, click the magnifying glass icon and it shows a listing of all categories.
Click on the desired category. A KB can only be in one category. If it needs to be in others, you must create a shortcut.

All About Headings

Using headings properly is important for accessibility.

The first title is an H1. A page can only have one H1 title, and this is entered when creating the page.
The first 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.

Never skip a level. For example, don't change from an H2 to an H4 just because it looks better—that is not accessible, and accessibility is the whole reason headings are used.

Here's where you choose the Heading:

Please don't bold or italicize headings.

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:

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.
Example;
- 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)
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?

You may have an article that could go in several different categories. Put it in the one that makes the most sense, then put shortcuts in other categories.

For example, under the File Storage and Sharing category, we have an article about the difference between different storing options:

Notice the anchor icon? This means the article actually lives in another category, but just has a shortcut in this category.

If you edit the shortcut, you will see it tells you at the top that it is a shortcut and that the breadcrumb shows the actual location:

You can edit the file at this point. You do not need to go to the actual location to do so.

To add a shortcut to a category

Navigate to the category where you want to put the shortcut.
Click +New Shortcut.
Either start typing the name or click the magnifying glass icon to search.

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:

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!

Creating a (Good) Knowledge Base Article

Body

Best Practices

An Example of a Well-Written KB

Details

Details