Style Guide

About

TeamDynamix Knowledge Base articles need to follow the KCS Style Guide before they are to be approved. This article covers the correct styles and rules to be followed when creating and publishing Knowledge Base articles.

Every article will be broken up into 5 sections: Issue/Question, Environment, Cause, Resolution/Answer, and Metadata. Not every article will require all sections but in most cases there will always be information under Issue/Question and Resolution. Each section of each article needs to have its corresponding header but if there is not information present for the section the section can be deleted.

Every article should follow the Style Guide Commandments. They are as follows:

1. Thou shall maintain the context of the client.
2. Thou shall remember the audience.
3. Thou shall not create duplicates.
4. Thou shall reference neither a client nor an incident.
5. Instructions shall be numbered steps.
6. Product names shall be proper.
7. Graphics shall be used as a last resort.
8. Attachments shall be visible.
9. Thou shall refrain from abbreviations and acronyms.
10. Thou shall use spell checker.

Along with adhering to the commandments every article should follow these style rules:

• All text should be set as Segoe UI. This is set automatically by TeamDynamix.
• Every section header (Issue/Question, Environment, Cause, and Resolution/Answer) should have a H2 formatting tag and bold. This is set automatically from the HTML Template.
• Sub headers need a H3 tag and bold.
• Headers below the sub headers need a H4 tag.
• All text beside headers needs to be 12 pt. size. This is set automatically by TeamDynamix.
• Error messages need to be 12 pt. size, and italicized. Quoted text should also have the block quote style applied to it by using the Block Quote button inside of the TeamDynamix text editor on quoted text.
• A word or phrase should be underlined if emphasis is needed past bolding.
• Quotation marks should not be used in articles. Any text that would have been between quotation marks should be bolded instead.
• Remove all white space at the end of an article.
• For information that would be important for the user to know before proceeding, refer to the HTML Template for preformatted templates

Article Category

Each article should be placed under the appropriate category. If no category fully fits the proposed article, please contact the Westmoreland Service Desk.

Article Subject

Each article should be given a correct and briefly descriptive subject. Verbs used in the subject should be written in the present participle tense (verbs with an -ing suffix). 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. Do not include the system or item it pertains to in the subject if that is the name of the category it is placed in. Search the knowledge base prior to creating the knowledge article to check for similar subjects and ensure that the new subject will not be confused with other, unrelated articles.

An example of a good subject for an article is as follows:

Inserting Special Characters

An example of a poor subject line is as follows:

How to Insert a Special Character in Windows 7

Issue/Question

This section should state the issue/question for the article clearly. This should be worded so any person who is searching the Knowledge Base can easily locate the article. If there is an error message associated with the article it should be included in this section.

An example of a good Issue/Questions section is as follows:

When I try to open an attached file on an item or assignment, such as a picture, Word document, pdf, Excel document, etc… I get the following error: 

Access Denied: Resource does not exist or you do not have sufficient permissions to access this resource.

 

An example of a poorly written Issue/Question section is as follows: 

Students can't get to an item in Blackboard.

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 is information such as operating system, browser and version, make and model of machine, versions of the software, versions of software, or specific departments involved. If multiple factors are involved in the environment a tiered bulleting system should be used.

An example of a good Environment section is as follows:

• Google Chrome
  • Tegrity

 

An example of a poorly written Environment section is as follows:

This article pertains to using Tegrity in Google Chrome.

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 for an issue/question and is acceptable. If the known cause for an issue/question does ever surface it should be added to the corresponding article.

An example of a good Cause section is as follows:

The professor is hosting the file(s) in his/her MyFiles, and has copied the course from a previous semester, causing the link between the item and the new course to break.

An example of a poorly written Cause section is as follows:

The professor hasn't uploaded a file correctly.

The Resolution section of an article should include all information needed to achieve a resolution to the issue/question. As stated above, if the resolution involves steps to be followed it should be in a numbered list. The resolution should be written so that anyone unfamiliar with the issue can follow the steps and achieve the intended end result. Each instruction should be as descriptive as possible and have only one action to complete in each numbered step. Try to refrain from using images and screenshots in instructional steps unless they are absolutely necessary. If you need to add a note, code, format keyboard keys, or other indicators check the HTML template for preformatted templates.

An example of a good Resolution section is as follows:

1. Right-click the Cisco NAC Agent desktop icon.
2. Select Properties.
3. Click Compatibility.
4. Un-check Run this program in compatibility mode for.
5. Click Change settings for all users.
6. A new window will appear. Un-check the box labeled Run this program in compatibility mode for.
7. Click OK.
8. Click OK again.

 

An example of a poorly written Resolution section are as follows:

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".

A short summary about the article should be included. This can be left blank by the KCS I role for the KCS III role to write.

An example of a good Summary section is as follows:

Instructions for adding a TopperMail account to an iOS device.

 

An example of a poorly written Summary section is as follows:

This article explains how to add a TopperMail account to an iOS device.

Metadata is automatically generated by TeamDynamix at the bottom of every article. Metadata includes Article ID, Status, if it's published to the Knowledge Base, Author, and who last modified it.

Each article can house items within it. You can attach pictures, text files, and anything else that might be pertinent to the article. Do not attach images for instructions to resolve the issue/question. 

The built-in search function already searches the article's title, subject, and full text. Each article can have tags associated with it. This is where words can be used to direct a user to the proper article (but are not already in the article) allowing users to find the article with ease (e.g., a document attached to an article is not indexed by TeamDynamix's built-in search). Focus on adding tags that are not already existing in the article to improve visibility. Always tag the article in it's about a particular system (e.g., all Blackboard articles should be tagged #Blackboard).