Good programmers write code; the best do not forget about tickets

Write Close
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 rather informal atmosphere. We can call up, write letters, use chats, and instant messengers to communicate and discuss the progress of affairs. Informal communication has a positive effect on the mood of the team and forms a friendly and open atmosphere, but 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.
With this course of events, 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 for all. 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 such a framework was chosen, how this or that algorithm works ... It will be more comfortable for everyone if he can see all the necessary information with his own eyes in the technical documentation and tickets, and not look in the office or chat for a person who will explain everything to him.

If you are working on a large project that solves many essential tasks of your business, a programmer who tells you: "Let's talk! We will hold a rally, 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. Each represents the world in its way, and its interpretation may not at all coincide with what you expected to see.

The consequences that such interaction may entail are 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, then focus on the ability to listen to the customer, convert his thoughts into tickets and explain 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, a lot of questions arise: what kind of quotation did not come, whether it should arrive at all, how to reproduce the problem, in what environment and other questions for which this ticket does not contain answers.
In this case, the programmer can only guess and seek out this quote. Well, if itssource and receiver in the project are only one, but there can be much more of them. Solving the problem by "selection" is a waste of time. It's good if the programmer guesses by some miracle and still finds it, but he can spend a lot of time pulling the door handles lock.

It happens that the bundle creates tickets after the planning session and they have only one name - this is not a problem, you can fill in the ticket with content later, but you must do this before the ticket is in operation.

It is much worse when the ticket closes, and the content has not been described. Before closing the ticket, you need to check whether its description matches the current state of things. If the ticket was closed and not described - 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 of the original contract (estimate, statement of work) - then you need to specify the item of requirements (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 number 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 *).
It is convenient to quote the words of the client (or a third-party expert) in the form of comments on the ticket, to which you can link from the ticket body. If all the requirements of the ticket can be understood from the text, then it makes sense to insert the entire section of the chat or letter into the body of the ticket. It must be clear from which chat or letter the requirement was taken when it was written.

The requirement for making links to the client becomes especially essential when the client asks for changes to an already agreed upon 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 the defect is most often called a bug report. This is a specific but ordinary type of ticket. It must be indicated in it:
  • play steps
  • observed behavior
  • expected behavior
  • instance (software version, environment) in which the defect was detected
  • test script
To write a good bug report, you need to prepare. If you find any mistake, don't run headlong into the bug tracker to start a ticket with the cries "nothing works!". To start, reproduce the error again. Reproduced - well, if not - it means that you did not take into account something and you need to try to reproduce it again.
When you understand what actions lead to this error, try to formulate its essence as concisely and concretely as possible - write a header for the bug report.

Bad headline: "Everything hangs when you paste the text."
Good title: "The editor freezes when pasting text from the clipboard using Ctrl + V."
The formula "What?" Helps to create an accessible description. Where? When?". 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 (that) 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 instruction for specific actions for another person. Replace the words "click, click, open" with the impersonal verbs "click, click, open."
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 period of time", you can exclude the words "for some reason", "pretty", "strange", "In essence" - without them, the meaning of your message will not be lost, but it will become more specific. The phrase "a certain time" can be replaced by a shorter synonym.

Tickets like "task" or "improvements" contain other main points. So, in the description of the task should be expressed:
  • The result (What needs to be done and for whom)
  • Solution Plan (How to do it)
  • Motivation (Why Do I Need It)
  • Admission criteria
A ticket of the "improvement" type must necessarily contain a description of the problem with the observed phenomena, give facts, after which 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 an absorber of hamburgers, I want to get a burger in a paper wrapper of three components (final result) so as not to get my hands dirty (motivation)
Acceptance criteria in this case:
1. I have a hamburger with meat, bun, and cheese
2. 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 are closed for weeks and contain a large number of messages are a pain. These tickets are hard to track; the essence and relevance of the task may be lost under the stack of messages 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.

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
Made on