Issue/Question
How do you structure a KCS Article
Environment
Cause
To make it easier to search and use articles they are structured
Resolution
TeamDynamix Knowledge Base articles need to follow a specific Knowledge Centered Services (KCS) standard when being created and published. This article covers the structural elements of the KCS Content Standard.
Article Category
Each article should be placed under the appropriate category. If no category fully fits the proposed article, place it under the best fitting category.
Article Subject
Each article should be given a correct and briefly descriptive Subject containing the main issue and environment. Verbs used in the subject should be written in the present participle tense (verbs with an -ing suffix) where possible. If there are any identifiers that could separate an article from another similarly titled article, include these inside of parenthesis at the end of the subject line. Search the knowledge base prior to creating the knowledge article using different key words pertaining to the environment and issue to check for similar subjects and ensure that the new subject will not be confused with other, unrelated articles. Should be written like a Movie title or a book title. Important words capitalized, others lower case
A well-written subject for an article:
Inserting Special Characters in Windows
A poorly written subject line:
How to Insert a Special Character in Windows 7
Article Structure
Every article will be broken up into 5 sections:
- Issue/Question
- Environment
- Cause (Not every article will require the Cause section.)
- Resolution/Answer (not every article will have a resolution to begin with)
- Metadata (Metadata is generated automatically by TeamDynamix and is currently not editable, with one exception of the KCS Article Status)
Each section needs to have its corresponding header but if information is not present, delete the section. The sections are described in more detail below.
Issue/Question
This section should state the issue/question associated with the article in clear concise thoughts, not sentences, in the customer’s context and without reference to the customer. It should be written using keywords to improve searchability of the article in the Knowledge Base. If there is an error message associated with the article it should be included in this section.
A well-written Issue/Question:
When opening an attached file on an item or assignment, I get the following error:
Access Denied: Resource does not exist or you do not have sufficient permissions to access this resource.
A poorly written Issue/Question:
Students can't get to an item in Blackboard.
Environment
The Environment section of an article should describe and encompass any factors that contribute to the issue/question. Examples of what should be included in the Environment section are information such as the operating system, browser and version, make and model of machine, versions of software, or specific departments involved. If multiple factors are involved in the environment a tiered bulleting system should be used.
A well-written Environment:
- Internet Explorer
- Colleague
A poorly written Environment:
This article pertains to using Colleague in Internet Explorer.
Cause
If there is a known cause for an issue/question it should be included in this section. When an article is first created, there may not always be a known cause, and this is acceptable. If the known cause does ever surface, it should be added to the corresponding article. The customer should never be referenced in the Cause section.
If the Cause is unknown at the time the article is published, the Publisher will remove the Cause section
If there are more than two causes, use the phrase “Multiple causes”
A well-written Cause:
Copying from a previous semester caused the link between the item and the new course to break.
A poorly written Cause:
The professor hasn't uploaded a file correctly.
Resolution
The Resolution section of an article should include all information needed to resolve the issue/question. If the resolution involves steps to be followed, they should be numbered. The resolution should be written so that anyone unfamiliar with the issue can follow the steps and achieve the intended result. Instructions should be as descriptive as possible, and each numbered step should contain only one action to be completed. Try to refrain from using images and screenshots in instructional steps unless they are absolutely necessary.
Nested steps will start with a number, lower case letter, lower case Roman numeral.
Links in the resolution should open in a new page (This needs to be specified in TeamDynamix).
The phrase for instructions should be used as a lead-in when linking to another article. Use the title (subject) of the other article as the hyperlink text.
Use Go to for external hyperlinks.
If directing to another department, link to that department's contact page
If there are steps for ITS technicians only which can be seen by the public, insert the ITS Staff Only box for those steps. The icon is a grey box located in the upper right hand corner. The ITS Staff Only box can be seen by everyone.
Note: When upgrading to TD 10.3 this button was lost. Please use the templates or copy the source code from another article as a temporary work around until after the TD upgrade on 9/20/2019. At that time we will work on getting the box back.
If there are steps for ITS technicians only which Should NOT be seen by the public, The Resolutions steps should be updated with the information the customer should provide and the ITS Internal box should link to the ITS internal article.
Example:
Please contact the Service Desk with the following information
- The change you would like to be made
- The name of the people affected
- Location of the issue (Building and room number)
- Asset number found on the NI label
A well-written Resolution section:
- Right-click the Cisco NAC Agent desktop icon
- Select Properties
- Click Compatibility
- Uncheck Run this program in compatibility mode for
- Click Change settings for all users
- A new window will appear. Uncheck the box labeled Run this program in compatibility mode for
- Click OK
- Click OK again
A poorly written Resolution section:
1. Right click on the NAC icon
2. Click on properties.
3. Click on compatibility
4. Un-check the box for "run this program in compatibility mode for"
5. Click the Change settings for all users
6. Un-check the box labeled Run this program in compatibility mode for
7. Click "ok"
Summary
Add a summary. A summary should provide context and any additional information not provided in title to facilitate better searching. It helps distinguish between similar articles when searching and reduces the number of duplicates added. For instance, if the title is Problems logging into SNAP, the summary should include the word login so that if someone searches with unable to login they will also get this article as a result. Adding the cause can help those searching find the correct article.
Metadata
Metadata contains the following information and is automatically generated by TeamDynamix, unless noted otherwise.
- Article ID - the unique identifier assigned to the article
- Status - the current status of the article (Not Submitted, Submitted, Approved)
- Revision Number - the number of times the article has been modified
- Published - whether the article available on the internal client portal
- Public - whether the article available on the public, non-authenticated portal
- Owner - as you create the article you are automatically the creator and owner, the owner could be changed later
- Created - the date and time the article was created, and by whom
- Modified - the date and time the article was last modified, and by whom
- The ITS only section - this section is editable and contains information only visible to knowledge workers
Please contact the Service Desk if you need further assistance