Write issues, not tickets

The difference is not cosmetic

A ticket is something you file. It has a number, a queue, and an implied SLA. Somebody on the other side picks it up, does the thing, and closes it. The model is industrial: work arrives, work is processed, work departs. It is a model borrowed wholesale from IT helpdesks, and for helpdesks it is exactly right.

An issue is something you investigate. It names a problem the world has and asks what we should do about it. The model is editorial, not industrial — you are not processing a request, you are forming a position. That difference in framing is the whole game, and it shows up in the title before it shows up anywhere else.

Titles are the cheapest leverage you have

Most issues are read far more often than they are written. The title is the line that shows up in search, in the cycle view, in the standup, in the notification, in six months when someone is spelunking through history trying to understand why a decision was made. Spend the extra ten seconds.

A bad title describes a symptom from one person's seat: "Button broken." A good title states the problem so a stranger could act on it: "Save button does nothing on the invoice editor when the form has unsaved validation errors." The second one is longer, and that is fine. Length is not the enemy of clarity; vagueness is.

If you cannot write a specific title, that is a signal — not a formatting problem. It usually means you do not yet understand the issue well enough to work on it, and the honest move is to spend five minutes reproducing it rather than filing a fog of a sentence and hoping the assignee divines your intent.

Write for the person who has to act, not the person who filed

The body of an issue has exactly one job: give the next person everything they need to act without a meeting. That means the current behavior, the expected behavior, and the smallest reliable path to reproduce. For a feature, it means the user problem, the constraint, and what 'done' looks like — not a pre-baked solution smuggled in as a requirement.

Resist the urge to encode the solution in the issue when you only understand the problem. "Add a retry button" forecloses the conversation; "users lose their draft when the upload times out" invites the better fix you have not thought of yet. State the problem crisply and let the people closest to the code propose the mechanism.

One issue, one problem

The fastest way to make an issue un-actionable is to staple three problems together because they happened to annoy you in the same afternoon. Now it can never be closed, because some part of it is always still open. It becomes a graveyard for context.

Split ruthlessly. If two things can be shipped independently, they are two issues. Sub-issues exist for the cases where a problem genuinely has parts — break the parent down, let it derive its status from the children, and keep each leaf small enough to hold in your head. A tree of small, honest issues beats one heroic ticket that nobody wants to touch.

The payoff compounds

Teams that write issues instead of filing tickets end up with a searchable, durable record of every problem they ever decided to care about and what they did about it. That archive is worth more than any status report. It is the institutional memory that survives reorgs, onboards new engineers without a tour guide, and answers 'why is it like this' with a link instead of a shrug.

None of this requires a process change or a new tool. It requires treating the issue as a piece of writing — short, specific, honest — rather than a form to be cleared off your plate. Write issues, not tickets, and the rest of the system gets quietly better.