The Difference Between a Bug Report and a Complaint
‘The checkout is broken’ arrives in five channels from five users and contains zero information an engineer can act on. The same failure, properly reported — environment, steps, expected versus actual — is a ticket with a diagnosis half-written. The gap between the two is not user skill; it’s form design. Users will report anything through a structure that asks the right questions in the right order.
This template is that structure, built for the failure-reporting workflows of engineering and support teams: outages, defects, data oddities, performance regressions — anything where the software did something nobody intended.
The Reproduction Is the Report
Everything else is metadata; the reproduction steps are the payload. The form asks for them as numbered actions — one long text field with the format stated above it:
- Go to…
- Select…
- Enter…
- Expected: the cart updates. Actual: infinite spinner.
Beside it, the reliability rating — a multiple choice: reproduces every time, sometimes, once so far. Intermittent failures get different engineering treatment than deterministic ones, and the reporter is the only person who knows which this is.
Pin the Context
- Where it runs. Production, staging, or a specific environment — plus platform: browser and version, operating system, app build. ‘The app’ is not an environment.
- When it started. A date-time field for first observation — the anchor that lets engineers check what shipped, changed, or expired just before.
- Who it affects. One user, one team, everyone — the impact surface that, more than any technical detail, drives priority.
- The evidence. Screenshots, error text, console output, correlation IDs — attached via document upload. The correlation ID alone routinely saves a support round-trip.
Severity, Triaged
Reporters flag impact; the triage call belongs to the team. The form collects the raw ingredients — scope of impact, data at risk, workaround existence — and the on-call engineer sets the priority. Inbound reports fire a self notification to the on-call rotation, and webhooks create the ticket in the tracker the team already lives in, so the form feeds the workflow instead of competing with it.
From Incident to Postmortem
Resolved reports feed the postmortem pipeline: the response archive becomes the failure history — repeat offenders by component, incident clusters by release, the reliability trends that decide next quarter’s hardening work. The sibling technical intakes sit in the IT collection.
Frequently Asked Questions
Won't users skip a form this structured?
The structure is what makes it answerable — numbered steps and pinned choices are easier than composing prose. Teams that pre-fill what they know and only fill the reproduction find it faster than email, because the email would have generated three follow-up questions anyway.
Should end customers use this, or just internal teams?
Customer-facing versions trim to the essentials — what were you doing, what happened, screenshot — while internal reporters get the full engineering fields. One master form, duplicated and trimmed per audience.
How does this relate to our status page and alerting?
They catch the failures the systems detect; this catches the ones only humans notice — the wrong number on an invoice, the email that never arrived, the filter that behaves oddly. Monitoring and human reporting are complementary nets.
What belongs in the report and what belongs in the feature request?
Anything that worked before and broke is an incident; anything that never worked but should is a request. The form’s opening question makes that split explicit, and misroutes cost nothing — triage forwards them.