Write a bug report a developer can use
A good bug report is not a complaint, it is a set of instructions: the developer should be able to reproduce the bug on their own machine without asking you anything. Everything that serves that goal belongs in it, and nothing else does.
The shape
Always the same order, however small the bug. The form saves the developer from asking you back, and asking back is the reason reports sit untouched.
- Title: the bug in one sentence, with place and effect.
- Steps: numbered, starting from a point anyone reaches.
- Result: what actually happened.
- Expectation: what should have happened.
- Environment: machine, OS, build, input device, resolution.
- Frequency: three out of three tries, or once in twenty minutes?
An example
Bad: "The game crashes sometimes in the cave. Really annoying."
Usable: "Crash on entering the second cave while the torch is lit. Steps: 1. Start a new game. 2. Light the torch at the first campfire. 3. Take the left passage into the second cave. Result: the game closes with no message, three out of three tries. Expected: the cave loads. Environment: Windows 11, GTX 1660, 16 GB, build 0.8.3, keyboard."
What goes wrong
Several bugs in one text: what is reported together gets filed together, and then half of it is forgotten. One report per bug, even when it feels repetitive.
The second trap is interpretation. Do not write what you think causes it, write what you saw. A guess is allowed, at the very end and marked as a guess.
Checklist
- One bug per report.
- Steps start from a point anyone reaches.
- Result and expectation kept apart.
- Machine, build and input device named.
- Frequency stated.