Writing tickets a remote developer understands

A remote developer can pick up a ticket without a call when it says why the work is needed, what will work differently afterwards and how you can tell it is done. If one of those is missing, the developer either guesses or waits, and both take more time than writing a good ticket.

I work as a developer from Serbia in client teams, and every day I pick up tickets someone else wrote. In an office you walk over to someone when something is unclear, but remotely it has to be in the ticket.

What a good ticket contains

This is what I want to find in a ticket as a developer:

• why it is needed and for whom, in one or two sentences
• the desired behaviour, seen from the user's side
• acceptance criteria you can check
• context, such as the design, the place in the code, earlier tickets and the thread where it was discussed
• what is deliberately out of scope

Describe the behaviour and leave the solution to the developer where you can. If you have a preferred approach, or there is a constraint, add it separately. Then the developer knows what is fixed and where there is room.

Acceptance criteria you can test

An acceptance criterion is good when two people would check it the same way without talking to each other. "The page loads fast" fails that test. "The list of 500 orders loads within one second on the test environment" passes.

Make the criteria concrete with examples. For a discount rule, write down what happens with an order of 100 euros and a 10 percent discount, and what happens with a code that expired yesterday. Examples like that often become the test cases straight away.

Given/When/Then can help, but you do not need it. A list of sentences you can tick off works just as well.

Context you have and the developer does not

Remotely you miss the conversations at the coffee machine and the customer call the ticket came from. What you know because you were there has to go into the ticket, such as what a customer asked for exactly, an agreement with another department or an earlier fix that did not work.

A screenshot of the problem or a short screen recording often saves a paragraph of explanation. Use test data or anonymised examples, though. Personal data from production does not belong in a ticket, and that includes screenshots. It is a GDPR matter, and an issue tracker usually has far more readers than your production database.

Link to the place in the code if you know it. "See the discount logic in checkout" sends someone searching, while a link to the file takes you a few seconds.

A definition of ready

A definition of ready is a short checklist a ticket meets before it goes into a sprint. Keep it short, or it becomes a form nobody fills in. A list like this is enough:

• the reason and the acceptance criteria are written down
• design and copy are done, if it touches the interface
• dependencies on other teams or external parties are known
• the team has discussed it and estimated it
• it fits in a few days of work

If a ticket is not ready, it does not go into the sprint. That feels strict, but a half-written ticket in the sprint means the questions come mid-sprint, after someone has already started.

The right size

A ticket that takes more than a week is usually too big. Split it into pieces that each deliver something that works, for example one discount type end to end first and the others after. Splitting into "backend" and "frontend" does not help much if neither piece delivers anything on its own.

A ticket like "refactor the order service" has no end point. Write down what will be better afterwards, for example that the price calculation can be tested in isolation.

Tickets that are too small cause trouble too. Ten half-hour tickets that all need the same context are better merged into one.

Before the developer starts

The developer has a part to play here too. Before I start, I write a comment on how I plan to tackle the ticket and what I am assuming. That takes five minutes, and whoever wrote the ticket sees straight away whether we mean the same thing.

My advice to clients is to walk through tickets with the developers before the sprint. In a remote team, that refinement session is where questions surface before someone has spent two days on the work. How to handle the follow-up questions without constant calls is covered in async work: what to write down.

An example: the expired discount code

I can pick up this ticket without a call:

Title: Expired discount code shows a clear error message

Why: customers with an expired code currently see "invalid code".
They should see that the code has expired, so they do not think
they made a typo.

Behaviour: for an expired code, checkout shows "This code expired
on [date]". Other invalid codes keep the current message.

Acceptance criteria:
- code that expired yesterday: message with yesterday's date
- code that never existed: current message "invalid code"
- valid code: discount is applied as it is now

Context: validation lives in checkout/discount.ts, the copy in
the translation files (nl and en). Use the existing error style.

Out of scope: cleaning up expired codes automatically.

The ticket is small, but a developer who does not know the product can start on it right away. A ticket like this also makes a good first task for a new developer, see onboarding a remote developer.