Want your bug reports to be clear? Don’t tell us about the bug in the repro steps.
If your bug reports include Repro Steps and Results sections, you’re half way to success. However, the other half requires getting the information in the right sections.
People have a hard time with this. Repro steps should be the actions leading up to the bug. But they should not actually describe the bug. The bug should get described in the Results section (i.e., Expected Results vs. Actual Results).
The beauty of these two distinct sections, Repro Steps and Results, is to help us quickly and clearly identify what the bug being reported is. If you include the bug within the repro steps, our brains have to start wondering if it is a condition necessary to lead up to the bug, if it is the bug, if it is some unrelated problem, or if the author is just confused.
In addition to missing out on clarity, you also create extra work for yourself and the reader by describing the bug twice.
Don’t Do This:
Repro Steps:
- Create a new order.
- Add an item to your new order.
- Click the Delete button to delete the order.
- The order does not delete.
Expected Results: The order deletes.
Actual Results: The order does not delete.
Instead, Do This:
Repro Steps:
- Create a new order.
- Add an item to your new order.
- Click the Delete button to delete the order.
Expected Results: The order deletes.
Actual Results: The order does not delete.
RSS
Also personally, I'd prefer the Actual Results line before the Expected Results line so that there's a reading continuation flow from the Repro Steps as I'd like to know what's currently happening.
In your example, I'd have to "jump" over the Expected Results to read the Actual Results then loop back to read the Expected Results.
+1 on comment for Result before Expected, for better reading flow.
There are also situations when you don't know what is expected, or have a couple of alternative solutions; where it would be confusing to have it in the middle.
I agree with this approach.
When i write bug reports, i first describe the encountered issue, after which i provide the steps to reproduce, then the Actual Results and then the Expected Results.
This is the approach that all the developers from the company i work for prefer and find it easier to follow in order reproduce and understand the bug.