Appendix E: Article Quality Quick Reference Guide

Issue/Question

As a matter of usability, it’s helpful to see clear, unique issues or questions when searching for articles. 

 

Issue: tell us what is happening in the requestor's words.

1. Don’t create “compound statements” - keep the environment terms out of the issue if you can.

No: Problem: 3Com NIC X1000 has the following error message: Comu.dll triggered an error in an invalid page in the module Comu.dll.

Yes: Problem: Error: “Comu.dll triggered an error in an invalid page”

Environment: 3Com X1000
Module – Comu.dll

    2. Make the thoughts complete:

Yes: Issue: Program crashes on startup with an error.

 

Issue: Error: “Program crashes due to insufficient memory”
 

Error Messages

Error: "<exact error message text>"

Error: “Cannot start program.  Required application not recognized”

Ordering Issues
If your article has multiple issue statements, order them in the article as follows:

• Less detailed first (generic)
• More detailed to follow (specific)

Example:

• Cannot print a file
• Error printing file to network printer
• Error: “Invalid page layout for this printer driver. (24301)”

 

The Most Reusable Error Structure

To structure error-statement-type issues for the greatest opportunity for reuse, structure Problems by breaking them into two "modular" statements:

1. a general statement that an error occurs, and the conditions during which it occurs
2. the specific error statement, with no conditional modifiers

Example:
If a requestor reports getting the following error:
Error: “Out of memory”
Error: “Error writing UDP packet 8101”
Error: “No document libraries available

 

Things you don’t need to write!
Certain phrases are unnecessary when writing statements:

• "I want to", "The customer is trying to"
• "The customer is using…"
• "The customer is getting…"
• "It worked okay before I…"

Just get to the point!

 

Verb Tense

Write in present tense: don’t tell us what you did, tell us what to do!

 

Use Explicit Subjects

Implicit Subject: Won’t print.

(Unclear - What won’t print?)

Explicit Subject: Documents do not print. (Better)

Environment Information

Naming platforms, products, versions, and/or functions.

 

Environment information should be formal and detailed, including as much information as necessary to uniquely identify the environment being described.

• <Vendor> <Product>, version <Version Number>

 

Examples of Good Environment Information

• OS X Yosemite version 10.10.5
• Microsoft Office 2016
• MacBook Air 

 

Environment Information helps Classify Problems

1. Do not put multiple Environments in a single statement.
2. Modify existing articles to add new Environments as needed:

Changes in the Environment

1. Think about what the user may have done:
   - Change:  Installed the update to the software
   - Change: Reset the counter to zero
2. Changes are not the cause - don’t confuse the two.
3. Do not jump to conclusions:
   1. No:    Change: It worked before we replaced an XBTVA with an XBTVM
   2. Yes:   Change: Upgrade from Release 3.2 to 4.0

 

Add unique environment statements to differentiate this article from others with similar symptoms but a different resolution

 

 

---

Resolution

Fixes or answers should address the problem or answer to the question

• The Fix statement clearly lists what steps to take to resolve the issue
• There can be multiple ways to resolve a problem, a formal fix or ways to workaround the situation, these can be documented in fix statements and should be labeled “workaround: “ 
• Fix statements should include active hypertext links to maintained web sites that are searchable by the users and in the context of the user.
• Use a link when helpful to point to existing documents or more details.

Structure of a Fix Statement

• Keep the whole fix within one "statement”. If several steps must be performed in order, number the steps.
• Use tabs for formatting and readability.
• Write everything as a present tense list of commands, as if you were reading them step by step to the customer.
• Do not include “if-then” statements in Fixes.  This is an indication that you need two separate articles differentiated by the environment statements.
• The article may contain more than one fix statement - but all Fix statements must be applicable.

The Cause (optional)

There should be only one cause per article. If an article has more than one cause, it is likely that it should be multiple articles.

If you must decide between applying one fix statement or another (because only one will work for your customer), the article should be split into two!

 

---

Article Audience

Indicates who can see which articles.

 

Internal: Visible only to users identified as employees

 

Partners: Visible to people who are not employees but act as trusted extensions of the organization

 

Customers: Visible to customers or users of our products or services

 

Public: Visible to unidentified individuals in the public domain

 

---

Article Confidence Transitions

Indicates progression of article through stages of confidence.

 

Work in Progress: Represents work in progress, no fix or resolution has been identified.

 

Not Validated: An article the author considers complete but they do not have high confidence in the resolution (not yet Validated). Or, the author is a KCS Candidate and is not licensed to create Validated articles.  Not Validated articles can be Validated through reuse.

 

Validated: Assigned to an article when a Contributor is confident in the resolution and the structure of the article. KCS Contributors and Coaches can validate articles.

 

Archived: This article is no longer relevant.  It is a candidate for archiving.

 

---

Article Governance

Indicates who can make changes to which articles.

 

Experience-based: Article is open to modification by licensed KCS users.

 

Compliance-based: Article creation and modification is restricted to designated individuals.