Description
TeamDynamix Knowledge Base articles are a valuable asset for technical technical teams. As such, it is important for these articles to have consistent formatting and writing style. This article covers the basic styles and rules to be followed when creating and publishing Knowledge Base articles.
Every article should contain two sections. Depending on the nature of the article those sections should have the following title.
For articles involving a problem and accompanying solution, the sections should be as follows:
- Problem
- Resolution
For articles detailing a specific situation and accompanying steps to completion (such as a software or hardware installation), the sections should be as follows:
- Description
- Procedure
If additional sections are needed, those may be added with the appropriate heading style.
Each article should be given a correct and briefly descriptive subject title. Verbs used in the title should be written in the present participle tense (verbs with an -ing suffix). 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.
The Resolution or Procedure section of an article should include all information needed to achieve the desired result. If the resolution or procedure involves a sequence of steps to be followed it should be in a numbered list. If it is a list of items, please use a bulleted list. The resolution or procedure should be written so that anyone unfamiliar with the issue can follow the steps and achieve the intended 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.
Style Guidelines
Every article should follow the Style Guide guidelines. They are as follows:
- Remember the target audience.
- Do not create duplicates.
- Never reference a client or incident.
- Instructions should be numbered steps.
- Product names should be proper names.
- Graphics should be used as a last resort.
- Attachments should be visible.
- Refrain from abbreviations and acronyms.
- Always use spell checker.
Along with adhering to the guidelines, every article should follow these style rules:
- All text should be set as Normal.
- Every section header should have a Heading 2 formatting tag.
- Sub headers need a Heading 3 tag.
- Headers below the sub headers need a Heading 4 tag.
- Error messages need to be 12 point size and italicized.
- Quoted text should 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, place a line at the beginning of the section starting with Note: in a bold, red font. Then type the important information in the normal black font defined above.
Each article should be placed under the appropriate category. If no category fully fits the proposed article, place it under the best fitting category.
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.