Cover photo by Christina Morillo from Pexels.
Developers often think that issue tracking is not that important, or even worst, they see it as some extra work they'll need to do in order to keep the boss happy. The truth is unless you are a lone wolf every minute you invest in having clear, concise descriptions for issues will pay off with gains. Even if you prefer to work alone or you are the only one currently working in a project, there are several benefits of spending some minutes properly creating and filling issues.
Bug and issue tracking software came to exist because of the need to work with ever increasing code bases, as software development evolves tools have become more and more sophisticated and what is to be a different tool is now considered the norm. Bug trackers allowed users to report and follow-up on bugs, issue trackers went one step ahead and allowed to also track feature requests, technical debt and other code related things that need to be discussed.
These days all code versioning tools (Github, Gitlab, Bitbucket, etc) include some sort of issue tracking and the best thing is that it is seamlessly integrated with many other code management features like boards and CI, still many teams have a hard time when they get to some size and they need to start following good practices and often rely on third-party software.
This post will walk you through what makes a good issue title and description no matter what tool you decide to use.
Anatomy of an issue
Title
The title should be short, descriptive and unique. It should be a single sentence.
The idea here is that people, particularly that involved in management, would be able to extract relevant information from the title without having to go to the details page. This is not just click economy, but sometimes you need to use several issues as working context and clicking around to extract information can distract you and make you forget things.
As a developer, in a daily meeting for example, you should not go into an issue to be able to get an idea of what it is about or briefly discuss it with other teammates. You should only see the issue's details page when you are working on it or need very specific information.
Description
This is the body of the issue. It should be actionable and offer a proper way of evaluate completion.
The reasons for issues being actionable is:
- An issue is a difference between the current state and the desired state.
- Something needs to be done and validated to mark the issue as complete.
- People working on the issue should be able to quickly evaluate if some work needs to be done.
The acceptance criteria is as important as the problem, it states what condition should be met for the issue to be considered done, it can save a lot of time to find disagreements about the acceptance criteria early on the cycle before much work has been done.
Tags/Labels
Tags are words that can be used to categorize the issue, as a general rule try to use as few as possible, these should help you find the issue easier, not confuse you or add any extra work by having to figure out ownership or state of progress.
The management perspective (also important to devs)
Issues are meant to make task simpler to track and to work upon, as the project grows it is normal that it becomes harder and harder to gather all the information to have issues that satisfy the conditions we discussed above.
To keep everyone happy, and not waste anyone's time, it is important to put particular attention in the acceptance criteria or definition of done. As a developer is a good idea to see it as an insurance policy, it allows you to estimate work before and and protects you from creeping scope. As a manager it helps evaluate performance and complexity in a sort of objective way.
Who will write them?
Issues can be written by developers, for small projects, or by project managers, team leads or scrum masters.
It is a good idea to learn how to fill proper issues even if you only care about development and don't plan to move into management any time soon, issue filling is a way to structure and systematize a task into discrete, achievable steps, which is the essence of engineering, it also helps to improve communication which is often seen as a very valuable skill many engineers lack. Vagueness in issue descriptions translates to procrastination, the more you need to stay away from the IDE and using other tools the more you are prone to be distracted and there is nothing more frustrating than moving some code to review and being said it is not meeting some requirements that was not previously specified, it demoralizes the developer and the reviewers and frustrates managers as well.
Issue writing is time consuming, it is not just about the time it takes to write the words in it, but also the time it takes to put things together, often you need to ask different people for information and validate with a few functional areas before the individual responsible for the task can start working in it. Depending on the size it might make sense for developers to work on this, but most of the time it is a good idea to have someone else assigned to writing them full-time, it must be seen as an investment, you have someone that enjoy doing this kind of job and that do it efficiently and allow developers to focus on the things they like, which usually don't involve these.
Make it a habit
Keep in mind that practice makes perfect and efficiency. Even if it is time consuming, the more issues you write the better you will get at it and the faster you will be able to write them. It is a skill as many others, if you openly ask for feedback and are willing to learn lessons from experience there is a lot of room for improvement.
There are some things that are left for later under the assumption that rules change for bigger players, proper communication and issues should not be one of those things, it is about habits and good practices, if you don't have the time know chances are you won't have it later, the same applies to money. This is not something that you can hire an expert to do, you definitely can hire and expert to tell you how to do it, but adoption depends on the whole team and it will be more difficult later on, beside the fact that you will always have someone arguing that it is not needed because it has not been needed so far.
Concerns
Issues have nothing to do with seniority or autonomy, it is common to hear that senior developers know what to do or that autonomous/independent professionals won't need detailed instructions but that is not the case, sometimes people alignment can help making this process implicit but at the end the better you define your problem the better anyone else will be able to solve it. The thinking should be made before start working on it, it can be in a meeting or totally asynchronously, it can be done by a single individual or collectively, but it is very important that the person accepting the issue is already fully aware of the acceptance criteria as stated in the issue.
Don't
Implement x feature
Do
Achieve this desired state by implementing x feature in this part of the code, with the following considerations.
in this part of the codegives some context of which files to touch.with the following considerationstalks a bit about the architecture, you don't have to go into implementation details but it is recommended to give some high level architecture details.to achievetells what will be tested to call it done.
Project management is a complex topic and issues are at the core of it, but I hope this post will help both developers and managers alike. I believe this topic is particularly hard for developers and engineers since it is usually left out of technical courses and it is seen as something external to the practice, it is not, often the difference between success and failure in technical projects is just planning, even if it is just to accept that it will take more time and money than expected, and to expect something in the first place.
Please consider spending a bit more time working in the issues definition to save a lot more time later on and for the sake of your team happiness.