Quick Quality Reference Guide for Writing Good Knowledge Base Articles

Quick Quality Reference Guide for writing good Knowledge Centered Service (KCS) Knowledge Base Articles part of the Content Standard with the following sections: Spelling Counts, Keyboard & Mouse Actions, Keyboard Names & Functions, Structuring an Article, Keep it simple, Be able to say yes to the following, need additional help

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