Knowledge Base Style Guide

(Last updated September 2026)

Purpose

This guide defines the standards for creating, formatting, reviewing, and maintaining Knowledge Base (KB) articles in TeamDynamix (TDX). It ensures consistency, ADA compliance, clarity, and usability across all Minnesota State institutions.

KB Templates and When to Use Them

Minnesota State currently has five KB types. Three are actively in use.

How To

• Step-by-step instructions for completing a task
• Use when: users need procedural guidance

Informational

• General information, definitions, explanations, or reference material
• Use when: no steps are required

Q&A

• Short question-and-answer format (FAQ)
• Use when: addressing common questions for a single topic

Problem & Reference

• Do not use at this time

Required Fields

Subject (title)

• Short, clear, and descriptive
• Should allow users to understand the topic at a glance
• Use service terms, not solutions, unless the tool name is required
  (e.g., ERP instead of Workday, Emergency Notification System instead of FinalSite)
• Avoid jargon, abbreviations, or internal-only terminology
• Use standardized capitalization

Examples:

• StarID Account Help – System Office
• D2L Login Instructions
• Multi-Factor Authentication (MFA)

Category

• Select the most accurate category available
• If no category fits or you are unsure, leave blank; KB administrators will assign one

Order

• Set to 1
• Used only for sorting within a category
• Do not change unless instructed by KB administrators

Pin Article

• Pin only when an article must appear at the top for all users
  (e.g., major outages, critical semester-start guidance, common issue)
• Pins should be considered temporary
• Review pinned articles at least every 90 days; unpin when no longer needed

Status

• Not Submitted → article is still being drafted
• Submitted → ready for review
• *Approved → KB admins publish after approval
• Rejected → not approved, may require revisions
• Archived → not active/visible; retained for record-keeping

*Authors should not publish articles themselves

Article Summary

• Helps users quickly decide if the article is relevant
• Brief, clear description of what the article covers; preferably 1 sentence
• Appears under the title in category lists

Example: “Provides login instructions and troubleshooting steps for D2L Brightspace.”

Tags

• Helps users find articles through search
• Use single-word tags
• Add as many relevant tags as possible

Examples: StarID, D2L, login, procurement, MFA, password, network, HR, ADA

Owner

• Must be a user or group
• Responsible for updates, accuracy, and annual review
• Always enable:
  • Notify Owner on Feedback
  • Notify Owner of Review Date

Audience

Audiences controls visibility of the article. Current audiences:

• Faculty – visible to faculty
• Staff – All – visible to all staff across Minnesota State
• Staff – IT – visible to IT staff across Minnesota State
• Students – visible to students
• Ticket Technicians – visible only to internal, TDNext technicians
• Group Permissions – currently not in use; avoid using until defined

If unsure, leave blank; KB administrators will adjust.

Body Formatting Standards (ADA-Compliant)

Headers

• Use clear, descriptive headers
• Avoid decorative characters or emojis
• Use Heading 2 for section headers; Heading 3 as needed for subsections
• Do not change the font or make font enhancements to headers

Font

• Use the tool’s default fonts, styles and colors
• Use standardized capitalization
• For ADA purposes:
  • Avoid italics and underlining
  • Use bold sparingly for emphasis
  • Use parenthesis sparingly for clarity

Color

• Do not change or adjust font or background colors

Lists

• Use simple, bulleted lists for scannability
• Avoid nested lists
• Use numbered lists only when order matters

Links

• Use meaningful link text
• Avoid “click here” language
• Ensure links open in a new window

Screenshots and Images

• Use sparingly
• Avoid images containing text unless necessary
• Must include alt-text descriptions for images

Attachments

• Attach only when essential
• Provide links instead of attachments whenever possible
• Provide a short description of each attachment
• Ensure all attachments are ADA compliant

Writing Standards

Plain Language

• Write for all users, including ESL readers
• Avoid jargon unless defined
• Keep sentences short and direct

Tone

• Use neutral, instructional language
• Avoid conversational phrasing
• Avoid “we” unless describing Minnesota State actions

Consistency

• Use the same terminology across all KBs
• Use service names over product names when possible
• Use Minnesota State naming conventions (e.g., StarID, TechID)

Accessibility

• Avoid long paragraphs
• Use headings and lists
• Provide alt-text for all images
• Avoid tables unless necessary for clarity
• Use quotation marks only when quoting exact text or button labels
• Use bold sparingly and only for emphasis
• Use parentheses sparingly and only for clarity
• Avoid using italics and underlined text

Related Articles & Related Services

• Associate only relevant, related KBs and services
• Avoid adding too many links
• Use when the item directly supports the user’s task or understanding

Review & Maintenance Standards

Annual Review

• Every KB must be reviewed at least once per year
• Update the Next Review Date accordingly
• Owners must ensure accuracy, accessibility, and relevance

Feedback

• Encourage users to submit comments
• Owners should respond promptly
• Use feedback to improve clarity and accuracy

Corrections

• If users report errors, review and make necessary updates as quickly as possible
• Document major changes in the article history as needed

Submission & Approval Process

1. Author drafts the KB
2. Set Status to Not Submitted
3. Complete all required fields; save as you go
4. When ready, set Status to Submitted
5. KB administrators review; may send back for revisions
6. KB administrators publish approved KBs
7. Owner receives notifications for feedback and review dates

Example KB Structure (Body Layout)

Overview (using Heading 2 format)

• Short paragraph describing purpose

Section Headers (using Heading 2 format)

• Bulleted or numbered lists.
• Heading suggestions: What it is, Why it’s used, How to use it, Where to get help, Useful links

Questions, Assistance, Feedback (using Heading 2 format)

• General statement on how to submit questions or get assistance and how to leave feedback on the article.