Product Quality's Ability: Bug Writing

Definition

Bug and Story balance detail and concision to provide a complete picture of the problem to be solved by engineering and a clear understanding of what “done” looks like. In cases where the problem to be solved is too large for a single bug or story, the problem is decomposed into multiple bugs/stories that provide a logical and sequenced path to done.

Why

Reporting bugs is the primary work product of a tester. While the ability to find bugs is the primary skill of a tester, the ability to communicate them cleanly and effectively to others is a close second in terms of letting the tester both deliver and demonstrate value.

I have observed this person showing a consistent, comfortable, continuous, and clear positive impact to a squad when wielding this ability, and therefore I would put them in situations where they can employ this ability with only a small amount of guidance

Follows a basic template with typed-out error messages

This first milestone is table-stakes for a tester: writing up a bug or story that is clear enough to product managers, engineers, and other testers that they can act on the story without asking follow-up questions. To facilitate effective asynchronous communication, a basic template must be used and followed.

Measurement: Stakeholder feedback and manual audit of bugs/stories show that they’re complete and easy to understand, using templated elements as appropriate.

I have observed this person showing a consistent, comfortable, continuous, and clear positive impact to a squad when wielding this ability, and therefore I would put them in situations where they can employ this ability, with no assistance as well as being a trusted active or passive mentor to others

Includes well-composed, specific screenshots/video where helpful

Some issues can be captured with text alone, some can’t be captured completely without an image or video. Most issues are somewhere in between. Providing images/videos where they add value and clarity turns good issue reports into great ones.

Measurement: Stakeholder feedback and manual audit of bugs/stories show that they include images/videos that enhance the clarity of the issue being reporting. Images and videos are focused on the problem and annotated when possible. Tickets do not include superfluous images or use images in place of including critical errors in the bug report’s text (making errors unsearchable).

I have observed this person showing a consistent, comfortable, continuous, and clear positive impact to multiple squads when wielding this ability, and therefore I would put them in situations where they can employ this ability as well as being considered an expert within this discipline

Includes technical observations (calling out network traffic, JS console messages, database state, Honeybadger/Papertrail reports)

Console messages, logging, and network traffic can help engineers isolate issues more quickly. When available, they should be included (whole or in part) in an issue report, with links to the external systems that capture the messages whenever appropriate.

Measurement: Stakeholder feedback and manual audit of bugs/stories show that they include console/logging messages that enhance the clarity of the issue being reporting. Tickets do not include large chunks of logging that the engineer must parse further, or use images in place of including critical logging text (making errors unsearchable).

I have observed this person showing a consistent, comfortable, continuous, and clear positive impact to a squad when wielding this ability, and therefore I would put them in situations where they can not only employ this ability but where they set the tone for this at the company level

Deviates from basic templates as appropriate

After demonstrating mastery of the preceding milestones, thoughtful and surgical use of those tools can lead to highly effective and efficient issue reports that deviate from the template.

Measurement: Stakeholder feedback and manual audit of bugs/stories show that stories are appropriately off-template but have brevity and clarity that accelerates both their creation and consumption.

I have observed this person showing a consistent, comfortable, continuous, and clear positive impact to not just internal teams but the community/industry in general when wielding this ability, and they are recognized by the community/industry as an expert

Attaches supporting data (example scenario data, JSON, etc.), links to test data

There are times where the test scenario that reveals a defect is complicated to set up or replicate, especially in a developer’s local environment. Know when to include test data and/or links to testable scenarios in a test environment (as opposed to doing so reflexively/automatically).

Measurement: Stakeholders report that they never have to go back to the tester for examples or data. Manual review by other testers confirms that data/scenarios are present in cases where they add value.