Maintaining work ticket

Last week I wrote about the purpose of the ticket and what should be in it. These assignments usually come from your product owners or directly from the business. Today, let’s assume that we have such a well-crafted ticket and we want to start implementing it.

When working on an assignment always be empathetic to the code reviewer, your colleagues and future developers — including yourself in 6 months. Try to make their (and your) job as easy and efficient as possible.

New information

Only few tickets contain the requirements and information necessary to finish the task at hand and it is inevitable that you’ll learn more as you move forward.

Therefore, it is essential to keep track of your gained knowledge in the ticket. That should include questions and answers about business requirements, the technical side of the implementation or the assumptions that you are making.

Logging these thoroughly serves as a great documentation, makes an easier job for the code reviewer and also leaves breadcrumbs in case another colleague has to take over your task.

If you are asking questions and answers come up in other formats (such as chat, phone, email, in person) you don’t have to wait for the counter-party to log them into the ticket and you can put the answer there for them. The only exception to that might be working in high-risk environments where having an official paper trail is important — like finance.

Reference the work

When you write some code, you should reference the code in the ticket and also reference the ticket from the code. The first serves to your colleagues and code reviewer and tells them which pieces are relevant to the assignment and the latter is useful documentation when using tools like git blame that might give additional context and history of decisions to your well-crafted commit message.

You can do this easily by agreeing on a few conventions around your branch names and commit message structures. Your ticketing system (e.g. JIRA) uses identifiers for tickets and you can use those identifiers as branch names and include them in commit messages.

At the moment, we use JIRA and the identifiers are structured as DEV-187. Therefore, when I pick up the task I create a branch (we also use git) and call it DEV-187. At that stage, anyone can follow my incomplete work by checking out the branch that follows a simple convention.

The other place where it is important to reference the task identifier is a commit message. It proved useful to follow a similar convention.

DEV-187 Short title

Additional context

The commit starts with the ticket identifier so you can immediately visit a URL of your ticketing system such as jira.example.com/browse/DEV-187 and view the content of the ticket as a documentation and background behind the original developers decision. Thanks to that, browsing a legacy code becomes a joy, or at least not such pain.

Lastly, you can automate those tasks with git hooks and write shell scripts to pull out documentation based on your branch or a commit.

Update status

Logging correctly the state of the ticket seems to be such a small thing to do but it makes a huge difference and developers constantly forget about it.

When you pick up the ticket assign it to yourself. That will prevent others to pick it up as well and duplicate the effort.

Your process might differ but make sure that you change the ticket after you complete each stage of it. For example, when the implementation is done and it is waiting for the code review change the status to waiting for code review.

Also, log in any additional information that is necessary to finish the task. If it is waiting for testing, note down the environment it has been deployed to so the tester doesn’t have to search for it.

By updating the status and logging it thoroughly your colleagues will know at any stage of the task where you are at without any unnecessary investigation. You are reducing their cognitive overhead and making their lives easier.

Conclusion

Keep the ticket up to date with obtained knowledge, reference your work by conventions and update the status regularly.

Be empathetic to your colleagues and try to make their job a walk in the park. By putting a little bit of extra effort into your tickets, you can create great documentation for future reference, an excellent starting point for a code reviewer or allow someone else to pick up the work in case you are sick or reassigned to another task.


Would you like to get the most interesting content about programming every Monday?
Sign up to Programming Digest and stay up to date!