How to Write an Accessible Article

Summary

Creating an accessible KB article in TDX ensures all users, including those with disabilities, can read, navigate, and interact with the content effectively. Below are best practices with examples and tips to meet accessibility standards.

Headings – Organize Your Content Properly

Why It’s Important: Headings help users scan and navigate content easily, especially those using screen readers or keyboard navigation.

Proper Heading Usage in TDX:

• H1: Reserved for the article title/subject (set automatically by TeamDynamix).
  • You will set this when originally creating the article. If you need to change the title(subject), click Edit Article -> settings.
  • The title should be action based. Users tend to look for articles when they want to accomplish a task
  • If the title is not a question, all words that are four or more letters should be capitalized. 
  • Titles should be brief. Use tags to expand on the topic for search ability. 
• H2: Used for main sections (e.g., Summary, Instructions, FAQs).
• H3: Used for subsections under H2 topics.
• H4 and lower: Only if needed for additional structure.

Example of Correct Heading Structure:

✅ Correct Usage:

• H1: How to Reset Your Password (Automatically assigned by TDX)
• H2: Step-by-Step Instructions
  • H3: Step 1 – Go to the Login Page
  • H3: Step 2 – Enter Your Email

❌ Incorrect Usage:

• H1: Password Reset Guide
• H3: Step-by-Step Instructions (H2 is missing—don’t skip levels!)
• H2: Enter Your Email (Should be under Step-by-Step Instructions as H3)

📌 Accessibility Tip: Never skip heading levels (e.g., don’t jump from H2 to H4). Screen readers rely on logical hierarchy for navigation.

Step-by-Step Instructions – Use Numbered Lists for Sequences

Why It’s Important: Numbered lists help users follow a logical process, ensuring they don’t miss steps.

Example of a Well-Formatted List:

Step 1: Go to the Login Page

1. Open your web browser and go to [Insert Descriptive Link].
2. Locate and select the "Forgot Password" link.

Step 2: Enter Your Email

1. Type your registered email into the provided field.
2. Click "Submit" to request a password reset.

When to Use a Numbered List:

✔ For step-by-step instructions
✔ When order matters (e.g., setup, installation, troubleshooting)

📌 Accessibility Tip: If order doesn’t matter, use a bulleted list instead of a numbered one.

Use Bulleted Lists for Related Items

Use bulleted lists to group related information when the order does not matter.

Example – Password Requirements:

• Must be at least 8 characters long
• Include at least one number
• Use a mix of uppercase and lowercase letters

📌 When to Use a Bulleted List:
✔ For listing features, options, or tips
✔ When the sequence does not matter

Links – Use Descriptive Link Text

Why It’s Important: Screen readers often list out links separately from the content. Descriptive links help users understand where a link will take them.

Example of Accessible Links:

✅ Correct:

• Download the Canvas Accessibility Guide (PDF).
• Read more about WCAG 2.2 compliance.

❌ Incorrect:

• Click here to download the guide. (Vague and unhelpful for screen readers)
• More info on WCAG 2.2. (What is "more info" about?)

📌 Accessibility Tip: Links should make sense out of context— avoid generic phrases like "Click Here", "Read More", or "Go Here".

Images & Alt Text – Describe Visual Content Clearly

Why It’s Important: Users who rely on screen readers or text-only browsers need alt text to understand images.

How to Write Effective Alt Text:

• Be concise but descriptive.
• Avoid "image of" or "picture of"— screen readers already announce it as an image.
• Do not use phrases like “image  of” or “picture of” (screen readers announce this automatically).
• If the image conveys important data, describe the key points.
  • Ex: An arrow or highlighted text in the image

Example of Proper Alt Text:

✅ Correct:

• "Error message: Password must be at least 12 characters long."
• "Illustration of a login form with a password reset link."
• "Screenshot of login page with the 'Forgot Password' link highlighted in yellow."

❌ Incorrect:

• "Screenshot of an error." (Too vague—what’s the error?)
• "Graph showing sales data." (What does the graph represent? What’s the trend?)
• “Screenshot”

📌 Accessibility Tip: If an image is decorative, set the alt="" attribute so screen readers ignore it. Be descriptive but concise (under 125 characters).

Tables – Use for Data, Not Layout

Color & Contrast – Ensure Text is Readable

Why It’s Important: Users with low vision or color blindness need high contrast to read text easily.

Contrast Ratio Guidelines:

• Regular text: Minimum 4.5:1 contrast ratio.
• Large text (18pt or 14pt bold): Minimum 3:1 contrast ratio.

Example of Good vs. Bad Contrast:

✅ Good Contrast (Passes WCAG 2.2)

• Black text on a white background (#000000 on #FFFFFF)
• Dark blue text on a light yellow background (#000066 on #FFFF99)

❌ Poor Contrast (Fails WCAG 2.2)

• Light gray text on a white background (#CCCCCC on #FFFFFF)
• Red text on a dark background (#FF0000 on #990000)

📌 Accessibility Tip: Use a contrast checker like WebAIM’s Contrast Checker.

Keyboard Navigation – Ensure Full Keyboard Access

Why It’s Important: Some users cannot use a mouse and rely solely on the keyboard.

Best Practices for Keyboard Accessibility:

✔ Ensure all buttons, links, and form fields are reachable via Tab.
✔ Provide a visible focus indicator (highlighted border) for active elements.
✔ Avoid keyboard traps (elements where users get stuck and can’t navigate away).

📌 Accessibility Tip: Test keyboard navigation by pressing Tab through the page— ensure you can reach and activate every element.

Troubleshooting & FAQs – Use a Q&A Format

FAQs help address common issues and provide quick solutions.

Example:
Q: What if I don’t receive the reset email?
✅ Check your spam folder.
✅ Make sure you entered the correct email.
✅ If you still don’t receive it, contact support.

📌 Accessibility Tip: Keep answers short and scannable.

Final Accessibility Checklist – Review Before Publishing

✅ Use proper heading structure (H1, H2, H3, etc.)
✅ Provide alt text for images
✅ Ensure links are descriptive
✅ Use high-contrast text and backgrounds
✅ Ensure keyboard navigation works
✅ Run an accessibility checker (e.g., WAVE, Axe, or TDX built-in tools)

By following these guidelines, your TDX KB articles will be fully accessible, WCAG 2.2 AA compliant, and easy to navigate for all users. 🚀