'It doesn't work' is technically a true statement about almost every bug and helps fix approximately none of them. A good bug report is the difference between a five-minute fix and a week of back-and-forth just figuring out what's actually being reported.
Beginner
2 min read
Why "it doesn't work" wastes everyone's time
A report that says only "the login page is broken" forces whoever picks it
up to ask several rounds of clarifying questions before they can even start
investigating: broken how? Every time, or sometimes? On which browser? Did
it error, or just do nothing? Each round-trip costs a day if the reporter
isn't immediately available — time that a slightly more detailed report the
first time would have saved entirely.
The five things a good bug report answers up front
1. What did you do? (exact steps, in order)
2. What did you expect? (the correct behavior)
3. What actually happened? (the incorrect behavior, specifically)
4. Can you reproduce it? (always / sometimes / only once)
5. What's the environment? (browser, OS, account, environment — prod vs staging)
BAD: "Login is broken."
GOOD: "Steps: go to /login, enter a valid email/password, click Sign In.
Expected: redirected to /dashboard.
Actual: page shows a spinner forever, no error, no redirect.
Reproduces: every time, on Chrome and Firefox, only on staging
(production login works fine).
Console shows: 'POST /api/auth 500 Internal Server Error'."
The second version doesn't just describe the bug better — it already
suggests where to start looking (staging-specific, a 500 from a specific
endpoint), which is the real payoff of writing it this way.
Small details that save the most time
The exact error message, verbatim, not paraphrased. "It said something
about a timeout" is much less useful than the actual text or a screenshot
— error messages often contain a specific code or detail that paraphrasing
loses.
Whether it's consistent or intermittent. A bug that only reproduces
"sometimes" is a genuinely different, usually harder, category of problem
(often a race condition or a specific data state) than one that reproduces
every single time.
What's different about the environment where it happens. "Works on my
machine, fails in staging" is itself an important clue, not a
throwaway detail — differences between environments are frequently the
actual root cause.
Why this matters day to day
A bug report is a form of technical communication like any other, and the
same instinct that makes for good documentation — answer the reader's actual
question, with a concrete example, up front — applies directly here. The
five minutes it takes to write steps, expected, and actual behavior
routinely saves far more than five minutes of back-and-forth for whoever
picks the report up next, whether that's a teammate or your own future self
two weeks from now.