Somewhere in every backlog there are two reports of the same class of problem. One gets picked up within a day. The other sits there for nine months and gets closed as stale. The difference is almost never the severity. It is how the report was written.
Nobody teaches this, so here is the shape that works.
Three lines first. What you did, what happened, what you expected instead. In that order, plain sentences, before any theory. If a reader cannot get those three facts in ten seconds, everything after it is wasted.
Then one exact example. Not a description of a category of failure, one instance of it, with the real order number, the real timestamp with a timezone on it, the real account, the endpoint you called and the response you got. One concrete case is worth five paragraphs of generalisation, because somebody can go and look it up.
Then the boring context, which is where most of the fixing time actually goes. Version or commit. Environment. Browser or client. Does it happen every time, or one in twenty. When did it start, and what else changed around then. What you have already ruled out, so nobody spends the morning repeating your afternoon.
Then the human impact, in one line. Eleven customers cannot complete checkout. Or, this is cosmetic and I can live with it until next sprint. Engineers are not reluctant to triage, they are reluctant to guess how much this matters.
A few things to avoid. Do not paste a screenshot of a screen when you have an error message you could copy as text. Do not trim the stack trace to the part you think is relevant. And label your theory as a theory, because a guess written as a fact sends a real person down a real dead end. I think it is the cache, but I have not checked, is an honest and genuinely helpful sentence.
Two quiet benefits. You will solve a good number of them while writing, which is embarrassing and excellent. And in three months, when it happens again, the person searching the tracker at midnight will be you.
– Asael Shinder
Top comments (0)