How to Write Better Tickets

Well-scoped tickets are crucial to GitStart shipping quality pull requests under a reasonable timeframe.

When tickets are clear and well-defined, we can deliver PRs with the highest quality and in the quickest time possible. On the flip side, poorly scoped tickets can cause delays and longer review cycles, and we definitely want to avoid that!

So, how can you write better tickets?

Create tickets by chat

If you’re not sure how to write a ticket, you can use our chatbot in the dashboard to help you create one. It will ask you a series of questions to help you define the problem and solution. This is a great way to ensure that you’re providing all the necessary information for the ticket.

Our LLM-powered chatbot has access to the sliced code you shared with us and will try to clarify UX/UI requirements, edge cases, and other details that might not be obvious from the ticket description. At the end of the conversation, you’ll have a well-defined ticket that you can review and assign to a developer.

Reduce uncertainty

We prefer not to make assumptions about what you want, because assumptions often lead to mistakes.

Here are some tips to help you reduce uncertainty:

• Set a few clear acceptance criteria. How will we know that the task is complete? What should we see or test to confirm that the task is done? Knowing this upfront helps us deliver what you want.
• State assumptions that might not be obvious. What is not said is often more important than what is said.
• Give us access to resources to complete the ticket. Depending on your ticket, this may include things like (access to) design files, access to staging or test environments, licenses, and any other resources that might be needed. We will ask for these if they are not provided.
• Provide guides that can help delivery. This includes references to internal documentation, similar issues, existing utilities, and previous implementation examples.
• Assign tickets not blocked by external dependencies. If tickets are linked to one another, it’s more likely to delay the release.

If these are not provided, our developers will make use of AI agents to analyze the slice of your codebase we have access to and ask clarifying questions about the business requirements.

The more you can provide upfront, the faster we can deliver.

Break it down

Did you know?

Studies on open-source projects show that smaller PRs are more likely to get accepted and merged. This is because they are easier to review and less likely to introduce bugs. If it’s true of open-source projects, it’s true of other projects too!

Monster tickets are hard all around: hard to estimate accurately, hard to code well, and hard to review, test, and merge. Why not break them down into smaller, more manageable tickets?

A ticket should solve only one problem. If a ticket consists of more than one problem-solution description, it shows that the ticket is bigger than it was supposed to be and can be broken down into pieces. One problem-solution example: “Build a button component with three different states”

A ticket is ideal if it takes less than five working days to complete, including testing and providing you with proof that it works.

Examples

A good ticket

Context The ‘Pricing’ section of the landing page is experiencing two main issues.

On resolutions above table (web), the paragraph is incorrectly placed on the left side of the screen when it should be on the right.

Secondly, the section has too many inline SVGs, making it cluttered and hard to read.

Requirements

• Fix the placement of the ‘Finance-team friendly’ paragraph. It should be on the right side of the screen for web resolutions only. No change to other resolutions.
• Extract the inline SVGs into separate files, format them, and import them into the pricing section using the Astro Image component. Follow the example in the ‘Supporters’ section for this task.

Acceptance Criteria

• The ‘Finance-team friendly’ paragraph is correctly placed on the right side of the screen for web resolutions and stacks on top of one another for tablet resolution and below.
• The SVGs are extracted into separate files named dollar.svg, merge.svg, and check.svg. They are properly formatted with correct indentation and are imported into the pricing section using the Astro Image component.

Additional Notes

Ensure that the changes do not affect the responsiveness of the ‘Pricing’ section. Test the changes on different screen resolutions to ensure the correct placement of the ‘Finance-team friendly’ paragraph and the proper display of the SVGs.

An incomplete ticket

“Fix the pricing section on the landing page. It’s not displaying correctly.”