How to Write Better Technical Issue Reports

“The page is broken” creates a second job for the person receiving the issue: discover which page, what broke, and whether the failure can be repeated. A strong technical issue report turns an observation into a testable statement. It gives just enough context to reproduce the problem, distinguishes what happened from what should happen, and protects private data while sharing evidence.

Start with a specific symptom

Write a title that identifies the affected action and the failure: “Saving an edited address returns an error after the confirmation step” is better than “Address bug.” Avoid naming a root cause unless you have verified it. A user-visible symptom can be confirmed by another person; an untested theory can send the investigation down the wrong path.

Record the impact separately. State whether the action is blocked, data is lost, a workaround exists, and who is affected. If the scope is unknown, say so. Do not turn one observed failure into a claim that all users are affected. Mozilla's bug writing guidelines ask for a clear summary, precise steps, and separate expected and actual results.

Make reproduction possible

List prerequisites first: account role, feature setting, browser or application version, relevant environment, and sample data. Then number the actions from a known starting state. “Open settings, choose profile, change the timezone, save” is more useful than “change timezone.” Include the exact button or route if it distinguishes two possible paths.

Run the steps again before filing, if doing so is safe. Note whether the failure happens every time or only sometimes. If intermittent, record the approximate timing and conditions you observed without inventing a percentage. Include the last known working version only when you have evidence, such as a successful run on a named build.

Try a smaller test case. Remove irrelevant data and steps until the failure still occurs. MDN's browser bug reporting guide recommends a minimal test case and expected versus actual behavior. The principle applies beyond browsers: a small failing input helps engineers isolate the boundary where reality diverges from expectation.

Separate observation, expectation, and hypothesis

State actual behavior in observable terms: the server returned a particular status, the form displayed a message, or an exported file had a missing row. State expected behavior from the product requirement, documentation, or established behavior. If the expectation is only your assumption, mark it as a question. A missing requirement may be a design issue rather than a software defect.

Put theories in their own line: “Possible relation: this started after the settings migration; not yet confirmed.” That wording keeps useful clues without converting speculation into fact. If you include logs, copy only the relevant interval and identify the timestamp and time zone. Redact access tokens, emails, payment data, and other sensitive values before sharing.

Explain what you tried. A report that says the behavior persists after refresh, in a clean browser profile, or with a second sample narrows investigation. Do not claim a cross-browser issue if you only tested one browser. Mozilla's guidance specifically calls out testing in a new profile when a Firefox issue may depend on local settings or extensions; adapt the isolation idea to your own product.

1. Name the affected action and visible failure in the title.
2. Record the environment, role, starting state, and safe sample input.
3. Write numbered reproduction steps and separate expected from actual results.
4. Attach minimal evidence with secrets and personal data removed.
5. Mark reproducibility, impact, attempted isolation, and open questions.

Hypothetical example: missing rows in an export

In this hypothetical example, an analyst reports that a CSV export from an orders page omits some rows. The first note says only “export is incomplete.” The analyst then makes a safe sample with three synthetic orders: one paid, one refunded, and one pending. The issue states the filter settings, export button used, application version, and the downloaded file's row count.

The expected result is three rows under the documented “all statuses” filter. The actual result is two rows; the refunded order is absent. The analyst checks the on-screen list and sees all three. The report attaches a redacted sample file and notes that the behavior repeats with the synthetic orders. No real incident or test result is implied by this hypothetical example.

Use templates without making reports rigid

A template can prompt the reporter for steps, expected result, actual result, version, and attachments. GitHub's issue template guidance describes forms with structured fields. Keep the required fields limited to information your team actually uses; too many mandatory questions invite guessed answers and abandoned reports.

Give an escape route for urgent security or privacy reports. A public issue tracker may expose the very data or vulnerability that needs controlled handling. Link to the private reporting channel from the template and ask reporters not to paste secrets into public fields. A screenshot is useful only if it contains evidence the text cannot convey; crop and redact it before attaching.

After filing, keep the report current. Add a confirmed reproduction, changed status, or validated fix as a dated comment. Avoid replacing the original observation with a later theory; preserving the initial facts helps explain how the investigation evolved. When a fix lands, verify the original steps and one neighboring case.

Issue-report checklist

• Does the title name the action and symptom?
• Are impact and affected scope stated without guessing?
• Can another person start from the listed environment and follow the steps?
• Are expected and actual results separate?
• Is intermittent behavior described honestly?
• Is the sample small, safe, and free of secrets?
• Are hypotheses marked as hypotheses?
• Is there a way to verify the eventual fix using the same steps?

The best issue report is not the longest one. It is the shortest report that lets another person witness the failure, understand its consequence, and check whether the repair worked.