Quick Quality Reference Guide for Writing Good Knowledge Base Articles

Issue/Question

How do I write a good Knowledge Centered Service (KCS) Knowledge Base Article

Environment

• TeamDynamix Knowledge Base

Resolution

Refer to the attached KCS Quality Reference Guide

1. Spelling Counts!

   • Spell and use words correctly
   • Capitalize the first word of each step
   • Acronyms must be universally known
     • Spell them out the first time (e.g. Knowledge Centered Service (KCS))
     • Following reference may use the pre-established acronyms (e.g. KCS)

2. Keyboard and Mouse Actions

• Open dialog boxes. Not appear or display
• Close dialog boxes. Not dismissed or cancelled
• Click a button. Not hit or press.
• Press a key on the keyboard. Not hit or depress
• Select an item from a drop-down list. Not click
• Check a check box or option button. Not click or select
• Tap something on the screen or a touch sensitive device. Not press or touch
• Go to HTML link
• Type text into a text box

3. Keyboard Names and Functions

• Use all caps
• Do not enclose in quotation marks
• Use the plus sign between keys that must be pressed at the same time. Use the actual key name
  • Press SHIFT+F8
  • CTRL+ALT+DEL
• Use Symbols from Font Awesome when appropriate (flag symbol in a box)

4. Structuring an Article

• Ask yourself these questions when writing an article
• Subject/Title
  • Does it contain description of main issue & environment, ex. Requesting access (Cognos) If possible use  verbs in present participle tense (verbs with a -ing ending).
• Summary
  • Does the title give enough context about the article? It should provide context and additional information not provided in the title to facilitate better searching.
• Issue/Question
  • What is the customer trying to do?
  • What is the customer asking?
  • What customer experience is undesirable?
• Environment
  • What system/software/hardware are involved?
  • Is the issue only specific to a certain environment?
• Cause
  • What is the underlying reason(s) for this issue
• Resolution
  • How do you fix the issue
  • What is the answer to the question
  • Do not use punctuation at end of each step

5. Keep it simple!

• Use short, familiar words. Avoid jargon and slang unless it is universal, audience appropriate, and contributes to reader understanding
• Use words only required to communicate intent
• Use complete thoughts not complete sentences
• Do not use punctuation at the end of each step
• Each step should be one action

6. Be able to say the following:

• No user names or passwords are mentioned!
• Used the KCS HTML Template?
• Article written in the customer’s context?
• Did you write what you know, not what you think?
• Included all steps necessary to convey the solution?
• Provided only content specific to the issue, not generalities?

7. Need additional Help?

• Reference the KCS Style Guide
• Email the KCS Coaching Team
• Submit Article Edits through the Knowledge Base

Please contact the Service Desk if you need further assistance