Why the quality of a report matters
When a bug is reported, someone else has to understand it, reproduce it, find the cause and fix it. Most of that effort is wasted if the report is vague. “It crashes sometimes” gives the fixer almost nothing: no starting point, no way to confirm a fix, and a lot of back-and-forth questions.
A good report does the reverse. It lets a person who was not there see the problem for themselves, quickly. Think of it as handing over a small experiment with all the conditions written down. The time you spend writing is nearly always less than the time saved.
The parts of a good report
1. A specific title
The title is what people see in lists and searches, so make it describe the problem. Compare:
- Weak: “Export broken”
- Better: “Export to CSV fails with an error when the file name contains a space”
A good title names what is affected and what goes wrong. It also helps others find the report and avoid logging duplicates.
2. Steps to reproduce
This is the most valuable section. List the exact actions, in order, that lead to the problem, starting from a known state. Number them and keep each one small and concrete.
- Open the application and sign in with a standard user account.
- Go to Reports and choose “Monthly summary”.
- Click Export and enter the file name “my report”.
- Click Save.
Include any data or settings needed. If the steps depend on a particular input file, attach it or describe it. Avoid phrases like “do the usual thing”; the reader does not know what that is.
Before you submit, try following your own steps from the start. If the problem does not occur, something is missing from the list.
3. Expected result
Say what you thought should happen. “A file named my report.csv is saved in the chosen folder.” This matters because what seems like a bug to you may be intended behaviour, and stating your expectation lets the reader judge. It also records the expectation against which a fix will be verified. Where a requirement or acceptance criterion defines the behaviour, point to it.
4. Actual result
Say what happened instead, precisely. “An error dialog appears reading ‘Cannot write file’ and no file is created.” Copy error messages exactly rather than paraphrasing them, since the wording is often searched for in the code. Describe visible effects: crashes, wrong values, freezes, delays.
5. Environment
Problems often depend on circumstances. Record what is relevant:
- Software version or build number, and how it was installed.
- Operating system and version.
- Hardware, browser or device details, if relevant.
- Configuration or settings that differ from the defaults.
- For hardware, the unit’s revision and serial number, and the test setup.
You do not need to list everything about your machine, only what could plausibly matter. If unsure, include more rather than less.
6. How often it happens
State whether the problem occurs every time, sometimes or only once. “Happens every time with these steps” is easy to work on. “Happened twice out of ten tries” tells the fixer to look for timing, data or state dependence. Be honest if you cannot reproduce it: a report of a one-off event is still useful if it describes what you did and saw, but say clearly that it is not reproducible so no one wastes time.
7. Evidence
Attach what helps:
- Screenshots or short screen recordings, marked up if needed.
- Log files or the relevant part of them. Trim to the relevant section, but keep timestamps.
- Sample input data that triggers the problem.
- A stack trace, if the program produced one.
Remove passwords, personal data and other sensitive information before attaching anything. Follow your organisation’s rules about what may be shared.
8. What you already tried
Mention what you checked, such as whether it happens on another account, a different file or an older version. Narrowing down the cause is useful: “Works with ‘myreport’ but not ‘my report’” points straight at the space character. If you know the last version where it worked, say so; that can shorten the search considerably, especially when changes are tracked in version control.
9. Impact
Give a sense of severity: does this block your work, corrupt data, or merely annoy? Is there a workaround? This helps whoever sets priorities. Report facts rather than urgency in capital letters. Triage is a team’s decision, and a calm description of impact is more persuasive than pressure.
One problem per report
Combine only closely related details. If you found three separate problems, file three reports. Each can then be assigned, fixed and verified separately, and none holds up the others. Before filing, search for an existing report; adding details to one that is already open is better than creating a duplicate.
Keep the tone neutral
Describe the behaviour, not who you think is to blame. “The export fails” is more useful and more friendly than “Whoever wrote the export code did not test it.” The reader is a colleague trying to help, and a factual report is more likely to get a fast response.
A short template
Title: <short, specific summary>
Steps to reproduce:
1.
2.
3.
Expected result:
Actual result:
Environment:
Frequency:
Attachments / logs:
Notes (what I already tried, workaround, impact):After you submit
Be available for questions. If the fixer asks for more detail, answer promptly. When a fix is released, try your original steps again and report whether it worked; confirming a fix closes the loop. Many teams also add an automated test for each fixed defect so it is less likely to return, an idea that sits naturally alongside the broader practice of software testing.
If you found the bug by running a test, the failing test is itself a precise reproduction and is worth attaching. And if you are the person hunting the cause, the habits in debugging strategies show how a clear report becomes a fast diagnosis.