Good programmers write code; the best do not forget about tickets
Do you have any questions? Contact us!
I agree the Terms of Service
published September 24, 2019
Usually, our communication in a team and with customers takes place in a relatively informal atmosphere. We can call up, write letters, use chats and instant messengers to communicate and discuss affairs' progress. Informal communication has a positive effect on the team's mood and forms a friendly and open atmosphere. But it also remains in the air, is not recorded in the documentation, and sometimes it can be challenging to return to it. It is merely impossible to recall what and with whom you agreed a couple of weeks ago. There is a high risk of getting into a situation where the customer says that he didn't want this, the programmers try to prove that they did exactly what he asked, then they begin to look for some mention in the chat and the catching of fleas begins.
In this scenario, the project becomes difficult to maintain.
In this scenario, the project becomes difficult to maintain.
Additional difficulties arise when the project team begins to grow and change - it is essential to keep the previous communications on the project in an understandable form. The developer, who just came to the project, probably wants to understand what has been done over the past year and get this information, not only in the form of code but also have some explanation for this code: why we chose such a framework, how this or that algorithm works ... It would be more comfortable for everyone if he could see all the necessary information with his own eyes in the technical documentation and tickets, and not look for someone who could give an extra explanation.
If you are working on a large project that solves many essential tasks of your business, a programmer tells you: "Let's talk! We will sit down together and decide everything. You will tell me what you need, and then I will go and code it. I will remember what we agreed on and program everything"- then I would think in your place what exactly he will do and in what form. We all envision the world differently, and its interpretation may not at all coincide with what others expect to see.
Such interaction may entail temporary losses and an increase in the customer's cash costs. That is why we try to convert any communication with the client into tickets and documentation, limited by the framework of our systems - Jira, Track, GitHub, etc.
If you want to develop as a professional and raise your level, focus on listening to the customer, converting his thoughts into tickets, explaining in an accessible way what has been done and what remains to your colleagues.
Now let's talk about how to create and describe tickets correctly.
Each ticket is an interaction of two people: the one who asks a question or designates tasks and the one who must solve these problems. When creating and describing a ticket, imagine that you are trying to explain something to your grandmother and your goal is to make sure she understands you.
If you are working on a large project that solves many essential tasks of your business, a programmer tells you: "Let's talk! We will sit down together and decide everything. You will tell me what you need, and then I will go and code it. I will remember what we agreed on and program everything"- then I would think in your place what exactly he will do and in what form. We all envision the world differently, and its interpretation may not at all coincide with what others expect to see.
Such interaction may entail temporary losses and an increase in the customer's cash costs. That is why we try to convert any communication with the client into tickets and documentation, limited by the framework of our systems - Jira, Track, GitHub, etc.
If you want to develop as a professional and raise your level, focus on listening to the customer, converting his thoughts into tickets, explaining in an accessible way what has been done and what remains to your colleagues.
Now let's talk about how to create and describe tickets correctly.
Each ticket is an interaction of two people: the one who asks a question or designates tasks and the one who must solve these problems. When creating and describing a ticket, imagine that you are trying to explain something to your grandmother and your goal is to make sure she understands you.
Consider an example:
In our system, the ticket "# 433 did not receive a quote" appeared, the descriptions were empty, the lead time was 4 hours, and the performer was that guy from the programmer's team.
Looking at such a ticket, many questions arose: what kind of quotation did not come, whether it should have arrived at all, how to reproduce the problem, in what environment, and other questions for which this ticket did not contain answers.
In our system, the ticket "# 433 did not receive a quote" appeared, the descriptions were empty, the lead time was 4 hours, and the performer was that guy from the programmer's team.
Looking at such a ticket, many questions arose: what kind of quotation did not come, whether it should have arrived at all, how to reproduce the problem, in what environment, and other questions for which this ticket did not contain answers.
In this case, the programmer can only guess and seek out this quote. Solving the problem by random trying the code is a waste of time. It's okay if the programmer guesses by some miracle and still finds it, but he can spend a lot of time pulling the door handles lock.
The project manager creates tickets after the planning session, and they have titles only — this is not a problem, you can fill in the description later, but you must do this before the ticket goes to operation.
It is much worse when the ticket is closed but the content has never been described. Before completing the ticket, you need to check whether its description matches the current state of things. If the ticket was closed undescribed - no problem, the closed ticket can also be edited and filled with content.
In the description of any ticket, it is essential to indicate the source of the requirements. It may be:
The requirement for linking the client's words becomes especially essential when the client asks to change an already agreed or developed software function.
Now, using an example of a ticket of the "Defect" type, let's look at the basic rules in compiling and describing a ticket.
The description of a defect is most often called a bug report. This is a specific but common type of ticket. It must be indicated in it:
The project manager creates tickets after the planning session, and they have titles only — this is not a problem, you can fill in the description later, but you must do this before the ticket goes to operation.
It is much worse when the ticket is closed but the content has never been described. Before completing the ticket, you need to check whether its description matches the current state of things. If the ticket was closed undescribed - no problem, the closed ticket can also be edited and filled with content.
In the description of any ticket, it is essential to indicate the source of the requirements. It may be:
- the conditions of the original contract (estimation, statement of work) - then you need to specify the item of conditions (and the document, and where to get it, if it is not clear where it is);
- the client's request expressed during a call or in correspondence - in this case, the client's words must be copied to the ticket;
- the requirement of the project manager or team leader - you must explicitly write about it "* First name Last name * said that the version should be only one number;
- by the recommendation of a third-party expert or colleague - you need to write about it explicitly, for example: "First name Last name <email address or nickname> says that Docker containers should contain no more than one service, so Dockers have it .."
- recommending an article on the Internet - be sure to provide a link (URL) to the item (for example: Make the version number according to * link *).
The requirement for linking the client's words becomes especially essential when the client asks to change an already agreed or developed software function.
Now, using an example of a ticket of the "Defect" type, let's look at the basic rules in compiling and describing a ticket.
The description of a defect is most often called a bug report. This is a specific but common type of ticket. It must be indicated in it:
- reproducible steps
- observed behavior
- expected behavior
- instance (software version, environment) in which the defect was detected
- test script
When you understand what actions cause this error, try to formulate its essence as concisely and concretely as possible - write a header for the bug report.
Bad headline: "Everything freezes when the user pastes text."
Good title: "The editor freezes when pasting text from the clipboard using Ctrl + V."
The formula "What?Where? When?" helps to create an accessible description. . Write what does not work, in what place, and under what conditions. By the way, it's good practice to start sentences with a verb. For example: "An unhandled exception (what) is thrown (verb) in the context menu (where) when changes are saved (when)." You can use the Gherkin language.
Bad headline: "Everything freezes when the user pastes text."
Good title: "The editor freezes when pasting text from the clipboard using Ctrl + V."
The formula "What?Where? When?" helps to create an accessible description. . Write what does not work, in what place, and under what conditions. By the way, it's good practice to start sentences with a verb. For example: "An unhandled exception (what) is thrown (verb) in the context menu (where) when changes are saved (when)." You can use the Gherkin language.
It is better to depersonalize the description because this is not a chronicle, but an instruction for another person's specific actions. When describing a problem, exclude all unnecessary words. It is terrible when there are a lot of words, but they do not carry valuable information.
For example, in the entry "For some reason, changing the values in the field works rather strange - in fact, updating the field occurs after some time", you can exclude the words "for some reason", "rather", "in fact" - without them, the meaning of your message will not be lost, but it will become more specific. The phrase "some time" can be replaced by a shorter synonym.
Tickets like "task" or "improvements" contain other main points. So, the description of the task should express:
For example, in the entry "For some reason, changing the values in the field works rather strange - in fact, updating the field occurs after some time", you can exclude the words "for some reason", "rather", "in fact" - without them, the meaning of your message will not be lost, but it will become more specific. The phrase "some time" can be replaced by a shorter synonym.
Tickets like "task" or "improvements" contain other main points. So, the description of the task should express:
- The result (What needs to be done and for whom)
- Solution Plan (How to do it)
- Motivation (Why Do I Need It)
- Acceptance Criteria
A ticket of the "improvement" type must necessarily contain a description of the problem with the observed phenomena and give facts. You can describe the option to improve the current implementation.
Remember that we said that everything should be clear, even to your grandmother? Here is an example of a ticket that can be used:
As a big fan of hamburgers, I want to get a burger of three components in a paper wrapper (final result) in order not to get my hands dirty (motivation)
Acceptance criteria in this case:
1. I have a hamburger with meat, bun, and cheese
2. The burger wrapped in paper
Remember that we said that everything should be clear, even to your grandmother? Here is an example of a ticket that can be used:
As a big fan of hamburgers, I want to get a burger of three components in a paper wrapper (final result) in order not to get my hands dirty (motivation)
Acceptance criteria in this case:
1. I have a hamburger with meat, bun, and cheese
2. The burger wrapped in paper
Remember that a ticket is not a chat! The ideal life cycle of a ticket is a discovery - a description of the problem - clarifying questions - a short explanation - a solution - closing a ticket. If the ticket is created, you cannot say "Okay, we'll figure it out later." When it is taken to work, all measures must be taken to resolve the problem, after which the ticket must
be closed. Tickets that have not been closed for weeks and contain a large number of messages are a pain. These tickets are hard to track; the task's essence and relevance may be lost under the stack of notes and comments.
Avoid "communication noise." Always address your question/request/ requirement to a specific person. When you write a comment, be sure to indicate the nickname of the person you are contacting. Otherwise, your comment can be considered as expressing your own opinion, which is not necessary to focus on.
Avoid "communication noise." Always address your question/request/ requirement to a specific person. When you write a comment, be sure to indicate the nickname of the person you are contacting. Otherwise, your comment can be considered as expressing your own opinion, which is not necessary to focus on.
Every time you write tickets, imagine that you are an artist who draws a line from point A to point B. Remember that tickets are an essential part of project work that can make your life easier.
Did you like this article?
Share article on social networks
Worked on the article:
Maria Ilchenko
PR and Event Manager
