As a technical writer, I’m often the first person to use a new widget or whatsit without knowledge of its internal function or composition, so I get to act as a surrogate user. Sometimes I spot bugs or areas for improvement that my developer colleagues have not, but before those things have been revealed to our customers (though it’s a credit to the skill of my colleagues that this is an unusual occurrence). Thus, I get to write bug reports and feature requests on a somewhat frequent basis. And I’ve come to a recurring pattern for reports and requests that has proven successful at getting those problems fixed and those changes made.
So today I present to you, with considerable commentary, my outline for writing up a bug report or feature request. These guidelines aren’t definitive, but they represent the kind of requests I’ve sent or received that got results, with a minimum of back-and-forth.
- Briefly summarize the request.
Ideally this should be no more than a few words. It should fit comfortably into the subject line of an email or your ticket tracker. This summary will probably become a mental shorthand that identifies a unit of work for somebody, so it’s kind to be terse. A terse summary often takes a simple form, such as noun verbs the object for a bug or noun should verb the object for a feature request.
If you can’t complete this step, stop and think things over before continuing. You might have more than one problem on your hands. Narrow it down a little, or you might make the recipient an unwitting contestant in a game of Twenty Questions.
- Describe the current situation.
Provide a context to compare the proposed change with the status quo. If it’s a bug, provide the steps to reproduce the bug. If you can’t reliably reproduce it, describe (in as much detail as you can) the conditions under which the bug appeared. If it’s a feature, just briefly describe how things work presently.
As both a reader and a writer, it’s easier to understand a proposal when there’s a contrast between the way things are and the way things you want them to be.
- Describe the desired outcome.
In other words, ask for the change. Don’t forget: be polite.
This is probably the thing that prompted you to start this process in the first place. If you’re requesting a bug fix, describe what you expected to happen. If you’re asking for a new feature, describe how a working implementation would behave.
Unless you’re knowledgeable about the specific implementation details, don’t speculate about how easy, hard, simple, or complex the changes required may be. It’s neither as helpful nor as convincing as you imagine.
- Describe the benefits of the change.
Justify your request. Describe how it will help your users, customers, or colleagues to live better, more pleasant lives. This is useful not just to convince the recipient to fulfill your request, but also to enable her to make an informed decision about which tasks to take on first.
- Describe the negative effects of the change.
If you can, describe how the change will require new effort or behavior on the part of your users, customers, or organization. You might suppose it’s counterproductive to describe the drawbacks of your proposed change, but ignoring drawbacks means ignoring opportunities to mitigate them. And occasionally you’ll have the good fortune to report that there’s no downside.
Here’s a made up example, based on the outline, to request a new feature for Gmail:
Feature request: Individual messages should have a delete button
Presently, to delete a specific message in a Gmail conversation, you must click the down arrow menu button in the upper right corner of a message, then click “Delete this message.”
Please add a button, perhaps alongside the existing forward button and down arrow menu button, that deletes the message in question when clicked.
The button would speed up the process of handling individual notification messages that Gmail has erroneously grouped together as a conversation. It would reduce the number of clicks in such a situation by 50%.
The addition of the button may cause some confusion for users when it first appears. During the adjustment period, some users may accidentally click the delete button and need to undo deletions more frequently than they would otherwise.
Please let me know if you require any additional information. Thank you for taking the time consider my request.
Honestly, it’s an iffy, high-risk feature—if I worked on Gmail, I’d probably reject it—but it contains some information on which to make that decision. On rejection, there’s an opportunity to identify alternatives, like fixing erroneous conversation grouping or providing a facility to split conversations. Those alternatives wouldn’t be apparent in a less detailed request, such as “Individual messages should have a delete button” alone. On acceptance, there’s enough information to determine what completion looks like (in this case, whether the implementation reduces clicks by 50%). Either way, a well-organized request makes it possible to find a good outcome.
And finding good outcomes is what making bug reports and feature requests is all about. So, with your help, we can make a less buggy, more useful tomorrow.