Issue Writing Philosophy
Issue writing, like all forms of writing is more of an art than science. Just as different flavors of narrative writing have shared idioms and patterns that help the reader understand it, well written issues have shared elements as well.
I tend to want to take a 3 step process when describing an issue. These three steps feel a bit repetitive, but they serve a purpose. By explicitly putting these three elements in writing it forces context out of your mind and on to the page, where we’re more easily able to spot inconsistencies.
Ultimately, we want to make sure that we are creating issues that allow who ever authors the issue to have confidence when they delegate and reduce time spent in development by eliminating the need to rework misunderstood issues
Say Something True About the Current State
When we are writing issues about new functionality, we want to describe what the user want’s to do. When we’re addressing an issue, let’s describe what is wrong.
Examples
- As a user, I want to be able to create new widgets in the dashboard.
- As a non-administrative user, I should not be permitted to change who is on my widget maintenance team.
- The Username field’s label is Usernom.
Tell Me Why It’s Wrong
When we’re writing about new functionality, describe why we are adding it. When we’re writing about a bug, explain why the existing functionality is wrong.
Examples
- Users need to be able to log a new widget type when they see one at a client’s worksite.
- Non-administrative users have been reassigning themselves to easier widget maintenance teams.
- Usernom is not an accepted spelling of Username.
How Will You Know It’s Done
Finally, lets describe the end state.
Examples
- Users should see a button on the dashboard called “Log Widget”, when they click on it they should see a form with fields for the name, worksite, and status of repair.
- Non-administrative users should no longer see the buttons to manage maintenance teams, if they browse to /teams/{team_id}/manage they should see a 401 Unauthorized screen.
- When a user loads the login screen the label should read “Username”
On it’s face, these three steps appear to overlap, but the three step process helps us reveal what we’re actually asking for. When we describe the initial state, we make sure we’re on the same page - are the developers and the requestor on the same page about where our starting state is?
By adding information about why something needs to change we can avoid the XY problem. Ensuring that we’re addressing the actual issue that the requestor wants to solve, not something that just appears to be related.
From Wikipedia:
The XY problem is a communication problem encountered in help desk, technical support, software engineering, or customer service situations where the question is about an end user’s attempted solution (Y) rather than the root problem itself (X).
Finally, by describing the done state we create a shared understanding of when the issue is resolved. We can write tests to enable TDD and be sure that when a PR is open it is fully resolved.