Issue Documentation

title: "Issue Documentation" weight: 17 description: "Learn how to document accessibility audit issues with unique IDs, WCAG references, severity ratings, screenshots, code snippets, and actionable fix recommendations for each finding." date: 2026-06-28 lastmod: 2026-06-28 tags: [accessibility, auditing]

Issue documentation in an accessibility audit captures every finding with a unique identifier, WCAG criterion reference, severity level, exact location (URL and selector), description, evidence (screenshot or code), and a specific remediation recommendation.

## What You'll Learn

You will create structured issue entries, include appropriate evidence for each finding, write clear remediation steps, and organize issues for different stakeholders.

## Why It Matters

Poorly documented issues waste development time. Developers need exact locations and clear fix instructions. Stakeholders need severity context and business impact. Well-documented issues get fixed faster and more accurately.

## Real-World Use

An auditor documents issue A11Y-042: a date picker that traps keyboard focus. The issue includes the page URL, the HTML element, a screen recording showing the trap, the WCAG criterion (2.1.2), severity (critical), and a code-level fix. The developer fixes it in 15 minutes.

## Issue Documentation Format

```mermaid
flowchart TD
  A[Issue Found] --> B[Assign ID]
  B --> C[Capture Location]
  C --> D[Describe Issue]
  D --> E[Add Evidence]
  E --> F[Assign Severity]
  F --> G[Write Fix]
  G --> H[Link to WCAG]
  H --> I[Ready for Report]

Documenting Issues

Each issue entry should contain all information a developer needs to reproduce and fix the problem.

<!-- Issue: Missing form label -->
<!-- Page: https://example.com/contact -->
<form>
  <input type="text" name="name" placeholder="Your name">
  <button type="submit">Send</button>
</form>

Documentation for this issue:

• ID: A11Y-015
• WCAG: 1.1.1, 3.3.2
• Severity: Critical
• Description: The name input field has no programmatically associated label
• Evidence: Screenshot showing input with no visible label
• Fix: Add a label element with for="name" attribute

/* Issue: Insufficient contrast */
/* Page: https://example.com */
.sale-price {
  color: #cc0000;
  background: #ffffff;
  /* Contrast: 5.2:1 -- passes AA for normal text */
}

.disclaimer {
  color: #999999;
  background: #ffffff;
  /* Contrast: 2.8:1 -- FAILS AA for normal text */
}

// Issue documentation data structure
const issue = {
  id: 'A11Y-023',
  wcag: '2.4.3',
  principle: 'Operable',
  severity: 'serious',
  page: 'https://example.com/checkout',
  selector: '#shipping-form .zip-input',
  description: 'Tab order skips from street address to country dropdown, missing ZIP code field',
  evidence: 'focus-order-recording.gif',
  expected: 'Tab order should follow visual order: street, city, state, ZIP, country',
  current: 'Tab order: street, country (ZIP skipped)',
  fix: 'Move ZIP input before country in DOM order or use tabindex to correct order',
  effort: 'small'
};

Common Mistakes

• Writing vague descriptions like "contrast issue"
• Not including the exact WCAG criterion reference
• Adding multiple issues in one entry
• Writing fix recommendations without code examples
• Forgetting to add screenshots or recordings
• Using inconsistent severity ratings
• Not linking issues to specific page URLs

Practice and Challenge

Practice 1: Document three issues from a page you audited. Practice 2: Write a fix recommendation that a developer could implement. Practice 3: Take a screenshot and annotate it for an accessibility issue. Practice 4: Create an issue template with all required fields. Practice 5: Write severity definitions for critical, serious, moderate, and minor.

Challenge: Create a complete issue documentation for a complex widget (a date picker or autocomplete field). Include: all WCAG criteria that apply, multiple screenshots showing the issue, a screen recording if applicable, DOM inspector output, and a step-by-step fix guide with code.

FAQ

Mini Project

Create a reusable issue documentation template in HTML or Markdown that includes: header fields (ID, page, WCAG, severity), description section, evidence section (image/video placeholder), fix section (before/after code), and a QA checklist. Populate it with 5 real issues from an audit.

What's Next

Severity and Prioritization covers how to prioritize audit findings by impact and effort.