Issue tracking systems employed by development teams can often be configured in a variety of ways, but they almost always have the same basic configuration that asks for essentially the same information. When creating an issue in an issue tracking system, the following guidance should be followed to ensure that developers can quickly and accurately fix the issues reported to them.
Summary (may also be referred to as “title”) – This should be a high level description of the issue, including where it exists. Because this field is usually a single line text input, it must be very concise and clear, such that anyone reading it can understand what the problem is immediately: “Registration form: Text input elements have duplicate ‘id’ attributes.”
Description – This would be where you’d enter a bit more long-form description of what this issue is about. In other words this provides the details on specifically what is the problem, where is the problem, why it is a problem, who is affected by it, how bad the problem is. Also include existing code and recommended changes to the code. If specific code examples can’t be supplied, use a text description. Always provide specific information on how to fix the issue. There’s no such thing as too much detail here as long as it is relevant to the specific issue you’re reporting.
For example:
Text inputs for “E-mail address” and “Desired Username” have the same value for their ‘id’ attributes. The value used for both ‘id’ attributes is “email”, but the “Desired Username” field’s label points to a nonexistent ‘id’ of “username”. This is likely a typo but will mean that users of screen readers may input the wrong text for one of these fields and may repeatedly fail validation while trying to figure out which field is which. All text inputs must have a
<label>element with a ‘for’ attribute that matches the ‘id’ attribute value of the corresponding input. The ‘id’ attributes must be unique.Existing Code:
<label for="email">Desired Username</label> <input type="text" name="username" id="username" /> <label for="email">E-mail Address</label> <input type="text" name="email" id="email" />Recommended Code:
<label for="username">Desired Username</label> <input type="text" name="username" id="username" /> <label for="email">E-mail Address</label> <input type="text" name="email" id="email" />
Platform – This information is most needed if there are specific platform issues to consider during debugging. If you’re unsure whether that’s the case, just include it to be on the safe side. Include your operating system & version, browser & version, and assistive technology & version.
Steps to Reproduce – This should include what it takes to see the problem first hand. This is really useful for stuff like focus management issues, but not so useful for basic stuff like form labels, alt text, or table headers which can be clearly articulated in the description, especially if you’re including code samples.
The following format is preferred:
Steps to reproduce:
- Go to Page X
- Activate the link labeled “Help”
- A dialog will appear titled “Get help from Y”
Expected Result:
- Focus would be shifted to the first actionable item in dialog
- Focus would remain in dialog only, until dialog is closed
Actual Result:
- Focus shifts to the first actionable item in dialog
- As they tab through, the user can gain focus on items outside of the dialog
By clearly and accurately describing the issue you’ve experienced, you can help the development staff understand the issue and guide them toward making a fix. Unclear, confusing, or incomplete issue reports only tend to delay repair while developers try to discover what the actual problem is. The better your report the more likely it will be fixed soon and accurately.
I also highly recommend reading Contacting Organizations about Inaccessible Websites