TeamDynamix - Style Guide for Knowledge Articles

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
• General Question
• 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 contain the CI the article is talking about. If it is not already part of the text, then add it to the end in parentheses
  • Example: "What Are the Access Levels for the VPN at MSU? (F5 Campus VPN)". Even though the Subject had 'VPN' in it, the CI name is 'F5 Campus VPN', so we added that to the end of the full Subject.
• 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
  • 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: <Description of Content>
• Example: Style Guide for Knowledge Articles (TeamDynamix)

General Question

• Format: <The question is the title>
• Example: What Are the Access Levels for the VPN at MSU? (F5 Campus VPN)

How To

• Format: How to <Description of Content>
• Example: 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: Error: "Oops. File Could Not Be Submitted" When Trying to Upload a File in D2L

Support Information Page (SIP)

• Format: <CI Name> 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 is also the text provided to the person who receives an article sent by the Share button. 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 the 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
• 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