Appendix E: Article Quality Quick Reference Guide
Following is an example of an Article Quality Quick Reference Guide that should be tailored to the environment.
Download the editable Word Document here.
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.
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
2. Make the thoughts complete:
Yes: Issue: Program crashes on startup with an error.
Issue: Error: “Program crashes due to insufficient memory”
Error: "<exact error message text>"
Error: “Cannot start program. Required application not recognized”
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:
Things you don’t need to write!
Just get to the point!
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)
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.
Examples of Good Environment Information
Environment Information helps Classify Problems
Changes in the Environment
Add unique environment statements to differentiate this article from others with similar symptoms but a different resolution
Fixes or answers should address the problem or answer to the question
Structure of a Fix Statement
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!
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.
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.