Product Ideas Portal

Replace "Description" and "Note" fields with "Issue", "User Impact", "Code Reference", etc. fields

Background

Currently, the structure of a standard violation instance has two main fields where we write up the issue: the Description field and the Note field.

Description field

The Description field has three default sections delineated by words in square brackets, like this:

[Issue]
Here we write a high-level description of the violation...

[User Impact]
Here we write about who it affects...

[Code Reference]
Here we optionally provide a code example (it's not always available, for example in mobile audits or with reflow issues)

Less common bracket indicators in the Description field include:

  • [Pattern: pattern name...]: Not a section starter, but it provides a way to make it more obvious that an issue is part of a pattern.

  • [WCAG 2.1], [WCAG 2.0 Level AA], etc.: Not a section starter, but it provides a way to make it more obvious which standard version the violation came from.

  • [ADVISORY]: Not a section starter, but marks the issue as advisory

  • [Occurrence]: A section starter that either lists the modules that a pattern came from in brackets, or lists them in bullets with a detailed description of how the issue affects the module

  • [Validation/Regression - DATE - DEFECT STATUS]: Can be a section starter with details about the failure or passing of the violation.

Note field

The Note field has two default sections.

[Recommendation]
General description on how to fix the issue across the site, with detailed guidance when possible

[Compliant Code Example]
Here we provide a generic code example or a more detailed one, when possible.

Problems

  • Some clients rely on this data to be highly structured for importing purposes, but it's easy to mistype one of the words in a square bracket, to forget a bracket somewhere, or to include excess newlines, which can break their importing code.

  • The non-descriptive titles of "Description" and "Note" can be confusing to clients and can make it difficult for them to find the information they're looking for.

  • The use of brackets to either start a section (e.g. [Issue]) or simply add a flag to a violation (e.g. [WCAG 2.1]) provides a mixed metaphor that can be confusing.

  • After several rounds of validation, the addition of [Validation] sections often causes the Description field to hit the character limit.

  • It might be difficult to implement enhancements like a spell-checker, Markdown editor, or code formatter in the present layout.

Possible solutions

  • Consider allowing separate fields for these sections:

    • Issue

    • User Impact

    • Code Reference

    • Recommendation

    • Compliant Code Example

    • Validation/Regression notes

  • For "flags" like [Pattern], [WCAG 2.1], [ADVISORY], etc., I'm not sure of the best solution, but I think it would be good to try to avoid having to write them out in the issue text.

  • Hadley Luker
  • Sep 4 2020
  • Attach files