Much of the time spent on bugs is not spent fixing them. It goes on working out what the person saw, on which device, after doing what. Messages go back and forth, the developer cannot reproduce the problem, and it gets marked as resolved when it is not. A well-written report cuts most of that out.

Anyone can learn to write a good report. It takes a few extra minutes, and it saves hours for everyone after.

Say what you did, step by step

The most useful part of a bug report is the list of steps that makes it happen. Start from a clear point, such as the home page after signing in, and write each action in order. If the developer can follow the steps and see the problem, it is usually halfway to fixed.

Try the steps again before sending. If the bug does not happen every time, say how often it appears, since intermittent problems need a different kind of investigation.

Say what you expected and what happened

Write both, plainly. “Expected: the order confirmation page. Actual: the payment page reloads with no message.” This separates the bug from a misunderstanding about how something should work, which is surprisingly common and also worth knowing.

Include where it happened

Note the device, the operating system, the browser or app version, and the account or test data used. Many bugs appear only on one type of phone, one browser or one kind of account. Without these details, a developer testing on a different setup will report that everything works.

Note the time it happened as well. Developers can often match it against server logs and find the exact error behind it.

Show it

A screenshot or a short screen recording often explains a problem faster than a paragraph. Mark the exact area that is wrong. For errors, copy the full message text as well, since the exact wording helps developers find where it comes from.

One bug per report

Combining several problems in one report makes it hard to track which are fixed. Keep each report to a single issue, with a clear title that describes the problem, such as “Coupon code rejected on checkout for saved addresses”. A good title makes duplicates easy to spot.

Keep the report updated as things change. If a fix is tried and the bug persists, add that to the same report rather than starting a new one.

Back to the journal