Skip to content
GitStart's Documentation

Writing Effective Tickets

Clear, well-defined tickets are crucial for GitStart to deliver high-quality pull requests efficiently. This guide provides best practices for creating tickets that lead to successful outcomes.

The Impact of Ticket Quality

Well-scoped tickets allow us to:

  • Deliver higher quality PRs
  • Complete work more quickly
  • Reduce review cycles
  • Minimize clarification questions

Conversely, vague or poorly defined tickets often lead to delays, misunderstandings, and additional review cycles.

Using AI-Assisted Ticket Creation

If you’re not sure how to structure a ticket, you can use our AI-powered assistance:

  1. Access our chatbot in the GitStart dashboard
  2. Describe what you need in conversational language
  3. The AI will ask clarifying questions about requirements, edge cases, and implementation details
  4. Review the generated ticket and make any necessary adjustments
  5. Submit the finalized ticket for assignment

Our AI has access to your shared codebase, allowing it to provide contextually relevant suggestions and clarifications.

Key Elements of Effective Tickets

Clear Context

Provide background information that helps developers understand:

  • The problem being solved
  • Where the feature fits in the larger system
  • Why the change is needed
  • Who will be using it

Specific Requirements

Define what needs to be built with precision:

  • Detailed feature descriptions
  • Behavior specifications
  • Exact functionality changes
  • Technical constraints or considerations

Explicit Acceptance Criteria

List clear conditions that define when the ticket is complete:

  • Measurable outcomes
  • Testable behaviors
  • Performance requirements
  • Quality standards

Supporting Resources

Include relevant materials that help developers implement the solution:

  • Design files or mockups
  • Links to similar implementations
  • References to existing utilities or components
  • Access to test environments if needed

Breaking Down Complex Work

Breaking large tasks into smaller, manageable tickets offers several advantages:

  • Easier estimation: Smaller tasks can be estimated more accurately
  • Smoother review process: Focused PRs are easier to review
  • Faster delivery: Smaller components can be completed more quickly
  • Reduced risk: Issues are identified earlier in the development process

Tip: A well-scoped ticket should typically take less than five working days to complete, including testing and verification.

Reducing Uncertainty

To minimize assumptions and miscommunications:

  • State explicit acceptance criteria: Define how to verify the work is complete
  • Document assumptions: Note any assumptions about the implementation
  • Provide resources: Share access to necessary design files, environments, or documentation
  • Identify dependencies: Note any tickets or work that must be completed first

Examples

Effective Ticket Example

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.

Ineffective Ticket Example

"Fix the pricing section on the landing page. It's not displaying correctly."

This vague description provides no details about what’s wrong, how it should be fixed, or how to verify the solution is correct.

Need Help?

If you have questions about creating effective tickets or would like feedback on your ticket structure, contact our support team at support@gitstart.com.