Body
Overview
This article is a best-practices guide intended to help employees author and edit content in TeamDynamix university-wide. This guide is not intended to cover more technical areas in TeamDynamix such as how to create a knowledge article, service, or how to process or handle tickets and service management. The guide is a comprehensive view of areas related to communications including but limited to how to write, what fields to use, tags, search, and more.
Table of Contents
Accessibility
Formatting is an important part of search engine optimization and accessibility. Follow these formatting guidelines when creating knowledge articles.
Web Accessibility Guidelines
To ensure that all users can access content in the knowledge base, and in accordance with Minnesota State policies, articles must adhere to web content accessibility guidelines. Read more about web content accessibility.
Screenshots and Images
Using screenshots, photos, and other images in instructional steps is not recommended due to accessibility issues. Images can pose challenges for individuals with vision impairment and those who rely on screen readers. Additionally, images may not scale well on different devices, leading to readability and user experience issues. Text-based content is preferred because it is more accessible, can be read by a screen-reader, and can be easily adjusted and updated. In some cases, images may be used to enhance pages for marketing, branding, or decoration purposes, so long as the images contain alt text, and all the important information is also available in text within the article.
Alt Text
If including an image is necessary, format it with appropriate alt text for accessibility.
Standard Terms and Phrases
Terms and phrases should be standardized to remain consistent across all content and ensure content is accessible. View the ITS Editorial Style Guide for guidelines on standard terms and phrases.
Knowledge Article Templates
All new articles should be created using the pre-made template options provided. These templates already have formatting applied. Review the template types and their use cases below.
How-To Article
Provides step-by-step instructions to help users complete a specific task or process.
- Example Use Cases:
- When explaining how to use a feature or tool.
- When guiding users through a setup or installation process.
- When demonstrating how to perform a specific action within a software application.
- Specific Example:
- An article on setting up multi-factor authentication
Troubleshooting Article
Helps users diagnose and resolve an issue they are encountering.
- Example Use Cases:
- When addressing frequent problems or errors users face.
- When providing solutions for technical issues.
- When offering guidance on what to do if a product or service isn't working as expected.
- Specific Example:
- An article on troubleshooting difficulties connecting to campus Wi-Fi.
Informational and FAQ Article
Compiles common questions, answers, or information related to a product, service, or topic.
- Example Use Cases:
- When addressing recurring questions from users.
- When providing quick answers to common inquiries.
- When offering a comprehensive overview of a topic through a Q&A format.
- Specific Example:
- Frequently asked questions or information about Workday.
General Best Practices for Titles
Titles help search engine optimization and are meant to help users quickly find articles related to their problem or question. All articles must have a descriptive, concise title.
Check for Existing Articles First
Search the knowledge base prior to creating the knowledge article to check for similar subjects and ensure the new subject will not be confused with other, unrelated articles.
Action Oriented
Whenever possible, the article should be action oriented. If the article is related to a software, do not put the software name first.
Examples:
- Correct: Signing in to Microsoft Outlook
- Incorrect: Microsoft Outlook: Signing in
Verb Tense
Use present participle tense verbs (ending in “-ing”) in the title.
Examples:
- Correct: Signing in to Microsoft Outlook
- Incorrect: Sign in to Microsoft Outlook
Point of View
Do not use first person language (I, me, my, we, our).
Examples:
- Correct: Verifying VPN Connection
- Incorrect: Verifying I'm Connected to VPN
Capitalization (Title Case)
- Capitalize major words: Nouns, pronouns, verbs, adjectives, and adverbs.
- Lowercase minor words: Articles (a, an, the), short prepositions (in, on, at), and coordinating conjunctions (and, but, or).
- Always capitalize the first and last word.
Examples:
- Correct: Signing in to Microsoft Outlook
- Incorrect: Signing In To Microsoft Outlook, signing in to microsoft outlook
Slashes
Avoid using slashes in titles or content. To ensure the language is clear to the user, instead use "and" or "or" in place of a slash.
Examples:
- Correct: Sharing Your Calendar or Mailbox in Outlook
- Incorrect: Sharing Your Calendar/Mailbox in Outlook
Ampersands
Avoid using ampersands (&) in titles or content. To ensure the language is clear to the user, instead type out the full word "and."
Examples:
- Correct: About Pay and Compensation in Workday
- Incorrect: About Pay & Compensation in Workday
Title Guidance for How-To Articles
For how-to article titles, use an action-oriented format. Start with a verb to indicate the action the user will learn to perform. Do not use the phrase “how to.”
Examples:
- Correct: Creating a New User Account
- Incorrect: How to Create a New User Account
Title Guidance for Troubleshooting Articles
For troubleshooting articles, use a problem-solution format. Clearly state the problem and the solution in concise terms, leading with the action whenever possible. Do not use the phrase “how to.”
Examples:
- Correct: Fixing D2L Login Issues
- Incorrect: Can't Log In to D2L, or How to Fix D2L Login Issues
Title Guidance for Informational and FAQ Articles
For informational and FAQ article titles, concisely list the subject matter. It may be helpful to begin with "About," but does not have to.
Examples:
- Correct: About Zoom Phone
- Incorrect: Frequently asked questions about Zoom Phone
Tags
All articles must have appropriate tags. Tags help with search engine optimization and grouping. Tags are visible under the article title. See the tags guidelines article for more information.
Summary
All articles must have a summary. Article summaries help with search engine optimization and are meant to help users quickly assess the relevance of the article to their problem or question. Summaries are visible in search results or in lists under the titles of articles.
- Summaries should be concise, one to three sentences. Do not just repeat the title of the article – provide a bit more information.
- Include key words related to the article, who the article is intended for, and what the article accomplishes.
- Use present participle tense verbs (verbs with an –ing suffix).
Examples:
- Correct example: Setting up multi-factor authentication as a student or employee using the Microsoft Authenticator app on a mobile device.
- Incorrect example: Setting up multi-factor authentication.
Related Articles
You can choose Related Articles in the settings of a knowledge article. Related Articles will appear as links in the bottom right corner of the published article. Don't relate every single article with a similar topic, this will just overwhelm the user and be unhelpful. Be intentional in choosing related articles and keep in mind the overall goal of helping the user. Here are some recommendations for when to add related articles:
- Topics that are directly related
- Topics that are frequently a next step
- Questions that are often asked together
Formatting
Section Headers
All section headers should be formatted as Heading 2.
Sub Headers
Sub headers under section headers should be formatted as Heading 3. Any sub headers below that should be formatted as Heading 4.
Body Copy
All text other than headers and sub headers should be formatted as Normal. Use the default font size, do not change font sizes.
Quotes
Quoted text should be formatted with Block Quote style.
Bold
Use bold to emphasize key words or phrases. Use bold when referring to specific buttons, menus, fields, or other features in the user interface that have visible names. Avoid bolding large amounts of text or entire paragraphs for accessibility reasons.
Examples:
- Correct: Select Log In at the top of the screen.
- Incorrect: Select Log In at the top of the screen.
Underline
Do not use underline to emphasize important words or phrases. Generally, on the internet, underlined words indicate that there is a hyperlink. Use bold instead to emphasize key words or phrases.
Italics
Using italics is not recommended due to accessibility issues. Use it sparingly if necessary, but in most cases use bold instead as a more accessible way to emphasize key words or phrases.
Quotation Marks
Quotation marks should not be used. Any text that would have been between quotation marks should be bolded instead. If it is a quote, use the Block Quote style mentioned above.
White Space
Remove all white space. White space is unnecessary between sections, paragraphs, or at the start or end of an article.
Notices, Notes, or Important Information
For important information, place a line at the beginning of the article or section starting with Notice: or Note: in bold font. Then type the important information in normal font.
Examples:
- Correct: Notice: MavLABS will be unavailable on Friday, March 2 at 10pm-11pm for scheduled maintenance.
- Incorrect: NOTICE - Users must be on campus to access this service.
Links
- Format links by highlighting the text and inserting the link.
- Insert the link directly into the text, do not display URLs. For accessibility, use clear and descriptive link text, avoiding phrases like like “click here.” This helps users with screen readers understand where a link will take them.
- Ensure buttons and links are navigable using a keyboard and have visible focus indicators to show where a user is on the page.
Lists
- Use bulleted lists for multiple items which do not have to be in any particular order.
- Use numbered lists for items that have to be in a certain order, such as steps or instructions.
- Remain consistent in writing style, never mix phrases and whole sentences in a list.
- Capitalize the first word on all list items.
- Use periods at the end of a bulleted item only if the item forms a complete sentence.
- In a bulleted or numbered list, add a line break (Shift + Enter) at the end of the text to move the cursor to the next line without creating another list entry.
Examples:
- Correct:
- In the Username field, enter YourStarID@minnstate.edu
- In the Password field, enter your StarID password.
- Select Log In.
Client Portal Search Prioritization Guide
The following table shows how different fields in knowledge articles are weighted in search. View TeamDynamix article
| Field |
Weight |
| Subject/Title |
10 |
| Tags |
6.5 |
| Category Breadcrumbs |
3 |
| Summary/Description |
2 |
| Attachment Names |
2 |
| Category Name |
1.5 |
| Body |
1.5 |