Write the issue for the person who picks it up in four months, who is you

There is a category of issue that nobody writes carefully: the one you file for yourself.

You are mid-way through something else, you spot a problem, and you write enough to jog your own memory later. "Fix caching on the settings page." "Timezone thing on invoices." Two seconds, and it works, because right now you have all the context and the note only has to be a handle for it.

Four months later the context is gone and the handle is attached to nothing.

The backlog is a message to a stranger

Anything that survives a quarter in a backlog will be read by somebody who was not there when it was written. Usually that is a colleague. Frequently it is the author, who has since shipped forty other things and has no more access to their own October reasoning than anyone else does.

The tell is a specific and slightly demoralising experience: finding an issue you wrote, agreeing it sounds important, and being unable to work out what it means. At that point the issue has negative value. It occupies a slot, resists closing because it might matter, and cannot be started.

Three sentences is usually enough

This does not need a template or ten minutes. It needs three sentences, and the third is the one everyone skips.

What is wrong. The observable behaviour, not your diagnosis of it. "Invoice dates show a day early for users east of UTC" rather than "timezone thing on invoices".

How you noticed. One line. This is what makes it verifiable later: without it, whoever picks the ticket up cannot confirm the problem still exists, and a large share of stale backlog issues are stale precisely because nobody can check whether they are still true.

Why you did not fix it then. The sentence that gets left out, and the one carrying the most information. "Needed a schema change" and "was in the middle of a release" and "could not reproduce on staging" imply three completely different pieces of work. Without it, the next person has to rediscover the obstacle you already found, which is the most wasteful kind of repetition there is.

The half-life of a link

A worked example beats a description, so link one: the failing run, the customer conversation, the Slack thread, the line of code. It costs a paste.

Two cautions. Links to chat tools rot, since retention policies quietly eat them, so paste the relevant three lines as well as linking. And a link to a line of code should name the function rather than the line number, because the number will be wrong within a week and confidently wrong, which is worse than absent.

What to do with the ones already in there

Every team has a backlog with a long tail of these. The instinct is to schedule a grooming session and work through them, which nobody enjoys and which rarely survives past the first hour.

A cheaper approach: leave them until they surface naturally, and apply one rule when they do. If you cannot tell what an issue means within thirty seconds, do not schedule it and do not investigate it. Close it, and say in the closing comment that it was closed for being unreadable rather than unimportant.

That sounds harsh and is mostly kind. An unreadable issue is not going to be worked on. Leaving it open advertises an intention that does not exist, and the real problem, if it is still real, will be reported again by somebody who can currently see it.

The general case

Everything above is the same rule that applies to issues filed by other people, pointed at yourself: the reader does not have your context, and no amount of familiarity with the codebase substitutes for it.

The difference is that when a colleague files something vague, somebody can ask them a question. When you file something vague for yourself, there is nobody to ask. You are the only person who ever knew, and you will not know for long.