How to Create Better Tickets

Use a clear and specific title. A reader should understand the purpose of the ticket without opening it.

Keep the ticket concise, but provide enough context. Write it so that someone including you can read it a year later and still understand the problem, the reasoning, and the required work.

Explain why the ticket was closed and what was done. Make the final status clear. Was the work completed, cancelled, rejected, replaced, or moved to another ticket? Anyone opening the ticket later should immediately understand the outcome.

Define the expected result or acceptance criteria. Clearly describe what must be true for the ticket to be considered complete.

Assign an owner. Every ticket should have someone responsible for moving it forward.

Include all relevant documentation and supporting information. Do not rely on conversations or knowledge that people currently have in their heads. Add the links, decisions, screenshots, technical details, and related tickets needed to understand the work later.

For example, instead of writing:

Update the model in the deployment.

In a year or a month you will have no idea what was model or deployment. Write:

Update the linked deployment to use the model checkpoint at the path below.