Knowledge Management - Style Guide for Knowledge Articles in TeamDynamix

Navigation

Select a link below to jump to that section:

• Article Subject
• Article Summary
• Article Body

Article Subject

The Subject is essentially the title of the article. It should inform the reader what type of article to expect, as well as what the article is about. The structure of the subject varies based on what type of article it is for:

• All Articles
• General Information
• How To
• Problem and Resolution
• Support Information Page (SIP)

All Articles

• Clarity is more important than brevity. Use enough words to distinguish the article from other similar ones.
  The Subject the first thing a person will see about the article, and it is the field given the highest priority when comparing search results.
• The Subject should start with the Service the article is talking about, followed by " - " and then the rest
  • Example: "Spartan 365 - General Information about Spartan 365 and Spartan Mail".
• Capitalization - in general:
  • Capitalize:
    • The first word of the Subject is ALWAYS capitalized
    • Adjectives
    • Adverbs
    • Nouns
    • Prepositions 4 letters or longer (Above, Between, Through, etc)
    • Verbs
    • "How To"
  • Lower-case:
    • Articles (a, of, the, etc)
    • Conjunctions (and, or, but, etc)
• Non-Public articles should end with a hyphen separating out the restrictions on the file, whether "Internal Only", "Restricted", or a more-specific indication of who the article is limited for viewing.

General Information

• Format: <Service> - <Description of Content>
• Example: Knowledge Management - Style Guide for Knowledge Articles in TeamDynamix

How To

• Format: <Service> - How To <Description of Content>
• Example: Knowledge Management - How To Archive a Knowledge Article in TeamDynamix

Problem and Resolution

• If the problem is an error, start the Subject with "Error: " and then put the error message in quotation marks. If possible, then add context about when/how the error happens.
  • Format: Error: "<the error>" <when/how the error happens>
  • Example: D2L - Error: "Oops. File Could Not Be Submitted" When Trying to Upload a File in D2L

Support Information Page (SIP)

• Format: <Service> Support Information - Internal Only
• Example: Spartan Mail Support Information - Internal Only

Back to Top

Article Summary

The Summary is an additional bit of text that a reader sees before they select to open an article. It should capture the main thrust of the article content and help them decide if this is what they need or not. Often this will resemble if not be a direct copy-paste of the Objective of a How To article, or the question of a General Question article.

Back to Top

Article Body

The Body of the article is where the main content resides. This is where the question is answered or the resolution steps provided.

• Write from the perspective of the intended audience
  • Keep jargon to a minimum, and explain its significance if it is unavoidable.
  • Spell out acronyms the first time they are used, and then put the term in parentheses showing how it will be written for the rest of the article.
    • Example: This is a Configuration Item (CI). The CI is . . .
• Whenever possible, avoid using text in paragraphs to represent lists
  • Use unordered lists when the order doesn't matter. Try to go in alphabetical order unless another sorting is more logical.
  • Use ordered lists to show priority or when steps must be followed sequentially.
• Screenshots - use the Add Collapsible Panel template to hide screenshots
  • If you have multiple panels, you will need to edit the source code unless you want all panels to expand/collapse whenever any individual panel is activated. The screenshot below shows the Switch parameters for two consecutive collapsible panels that will need to be edited. We recommend incrementing the number at the end for each new panel. The first will use Switch1, the second Switch2, etc. Note the period before the first "Switch#" is necessary, and must not be present for the second.
    Screenshot

    

• Emphasize content - use the Add ... Alert templates to call out specific information.
  • Informational - this blue text box indicates information that is useful, but that can be safely ignored.
  • Warning - this yellow text box indicates a possibility that something could adversely affect the user or service.
  • Danger - this red text box indicates a significant risk of adverse consequences for the action being described.
• Links
  • When creating a link within the article, always include (link) afterwards, to identify it as a link. To create a link:
    1. Highlight the text you want to form the link, then select the Link button from the editing panel at the top.
    2. On the Link Info tab, switch the Protocol to https.
    3. On the Target tab, switch the Target dropdown to New Window (_blank).
    4. Select OK.

Back to Top