Writing Tech Tickets

Leslie's photo
Leslie
·

4 min read

Writing Tech Tickets

Table of contents

đź’ˇ
This article provides guidance on the key details that will help teams define their tickets better. The samples are based on Jira and Scrum, but the fields remain relevant regardless of which issue tracker or management tool you use.

Ticket Hierarchy

This is a simple way of managing issues/tickets. There are more ticket types that can be used and you can create your own.

  • Epic - A big project or feature that takes weeks or months to complete

  • Task / Story / Spike - unit of work that contributes to the epic

  • Bug - same-level as Task but specifically for filing bugs found

  • Sub-task - smallest piece of work needed to complete the task

Ticket Details

These are some of the key information to help the team understand and manage work better. Most of these are default fields. Again, the ticket details can be customized.

Epic

  • Epic Title

  • Description - Objective of this epic

  • Confluence Link - Link back to the requirements document

  • Start Date

  • Due Date

  • Status

Task / Story / Spike

  • Summary (Title)

  • Description - What should be done and why

    • Can be written in gherkin so it’s easier for other stakeholders to understand

    • Add links to designs or documentation (if not available as another field)

    • For API creation, attach the OpenAPI specs

  • Acceptance criteria - How to know if that the goal of this ticket has been met

  • Attachments - Supporting documents

  • Environment

  • Component - Involved application, service, library, ML model, web component or similar

  • Fix versions - Release version (all tickets tagged under the same version are released together)

  • Status - Workflow status. Simplest flow is To Do → In Progress → Done

  • Sprint

  • Assignee - main assignee

  • Parent - the epic where the story/task belongs to

  • Linked issues - related tickets

  • Commits /deployments - automatically linked via tickets in commit messages

  • Labels - for better organization / filtering

Bug

  • Fields same as Task

  • Description

    • Issue statement

    • Expected result

    • Actual result

    • Steps to reproduce

    • Reproducibility

    • Platforms/components/versions affected (if not available as another field)

  • Acceptance criteria

  • Affects versions - All release versions that have the bug

  • Environment - where the bug has been detected

Sub-task

  • Summary (Title)

  • Description - What should be done and why

Notes on acceptance criteria details

Some items that may help in writing the acceptance criteria:

  • Expected functional requirements

    • If the OpenAPI specs is available, it can be as easy as it should follow the OAS, including authorization, request/response payload, success and error messages, headers. The whole contract

    • Check the UX/UI design, if applicable

  • See the Common non-functional requirements

  • Expected feature flags

  • Expected configurable items (e.g. limits)

  • Expected logs

  • Regression tests must be passing. (Sometimes a smoke test will do, depending on the ticket. But if the automation is available, why not regression?)

  • If the ticket requires performance testing, add the expected metrics and results

  • For spikes, be clear on the goal and the scope of the research or assessment

Notes on sub-tasks

Common sub-tasks:

  • Development

  • Unit Test

  • Code Review

  • SIT

  • Test case creation

  • Test case review

  • SAT certification

Sub-tasks can be automated. As much as possible, activities should be a part of the pipeline. Depending on how mature the CICD / DevOps of the team is, there may be more sub-tasks (or tasks) that will help ensure that all requirements are met and releasable to Production.

Learnings

  • The ticket types and fields to use and whole network of projects setup depend on the team’s workflow. The same for how to split tasks into epics and stories.

  • Epic should have a brief statement of the goal. When discussing during backlog grooming, it’s easy to help the team members understand why we are doing this. Members should not be just there to code without even knowing why.

  • Stories/tasks should be written in a way that’s easy for anyone to read, even non-technical people. Usually this can be achieved with gherkin. However, there are times when simple bullets and table matrix will be more direct and easier to understand. Especially for truth tables.

  • Scoping tickets. Do not mix unrelated requirements that will make a ticket more complex than it needs to be. Testing should be focused. And if the scope’s too big, it will be harder when something unexpected becomes a blocker and delays everything.

    • For example, creating just one ticket for three new endpoints and then a blocker happens.

      • If these are spread out into three tickets, when 1 endpoint’s done, the corresponding ticket can be closed immediately. If any blockers come up, the other two remain.

      • But, if there’s just one ticket for all three, that ticket will remain in progress/pending until the blocker has been lifted.

    • Basically, the faster a ticket gets closed, the better.

tech requirements
Â