etiquetteA team working remotely requires much stronger discipline than a co-located crew sitting in the same office. First of all, I mean discipline of communications. At Zerocracy, we have developed software remotely for the last five years. We manage tasks strictly through ticketing systems (like GitHub, JIRA, Trac, Basecamp, etc.) and discourage any informal communications, like Skype, HipChat, emails, or phone calls. Every ticket for us is an isolated task with its own life cycle, its own participants, and its own goal. Over these years, weâve learned a few lessons that I want to share. If you also work remotely with your team, you may find them useful.
1. Keep It One-on-One
Each ticket (aka âbugâ) is a link between two people: problem specifier and problem solver. If it is a bug, Iâm reporting itâyouâre solving it. If it is a question, Iâm asking for an explanationâyouâre explaining. If it is a task, Iâm ordering you to do itâyouâre doing it. In any case, there are two main characters. No matter how many people are involved in the ticket resolution, only these two characters have formal roles.
The responsibility of the ticket reporter is to defend the problem. When I report a bug, I have to insist that it existsâthis is my job. Others may tell me that Iâm wrong and the bug is not there. They may tell me that they canât reproduce it. They may say that my description of a task is too vague and nobody understands it. There may be many issues of that kind. My job is to do the best I can in order to keep the ticket alive. Obviously, if the bug is not reproducible, Iâll be forced to close the ticket. However, until the ticket is closed, Iâm its guardian angel.
On the other hand, the responsibility of the ticket solver is to defend the solution. When a ticket is assigned to me and I have to resolve it, my job is to convince the reporter that my solution is good enough. He may tell me that my solution is not sufficient, not the most efficient, or incomplete. My job is to insist that Iâm right and he is wrong. Well, of course, in a reasonable way. And in order to create a solution that will be accepted as sufficient enough, I have to understand the problem first, investigate all possible options, and propose the most elegant implementation. But all this is secondary. The first thing I will be focused on is how to convince the reporter. I will always remember that my primary goal is to close the ticket.
My point here is that no matter how many people are involved in the ticket discussion, always remember what is happening thereâone person is selling his solution to another person. Everybody else around them is help or distraction (see below).
2. Close It!
Remember that a ticket is not a chat. Youâre not there to talk. Youâre there to close. When the ticket is assigned to you, focus on closing it as soon as possible (Always Be Closing, remember?).
Also, keep in mind that the sooner you close the ticket, the better job you will do for the project. Long-living tickets are a management nightmare. It is difficult to track them and control them. Itâs difficult to understand whatâs going on. Have you seen those two-year-old tickets in open source projects that have hundreds of comments and no deliverables? It is a mistake by their project managers and ticket participants. Each ticket should be short and focusedâ1) a problem, 2) a refinement question, 3) a short explanation, 4) a solution, 5) closed, thanks everybody. This is an ideal scenario.
As soon as you realize that your ticket is turning into a long discussion, try to close it even faster. How can I close it if the reporter doesnât like my solution? Find a temporary solution that will satisfy the reporter and allow you to close the ticket. Use âTO-DOâ in your code or dirty workaroundsâthey are all better than a ticket hovering for a long time.
Once you see that the solution is provided and is sufficient enough to close the ticket, ask its reporter to close it. Explicitly ask for that; donât dance around with âlooks like this solution may be accepted, if you donât mind.â Be explicit in your intention to close the ticket and move on. Try this: â@jeff, please close the ticket if you donât have any further questions.â
3. Donât Close It!
Every time you raise a bug and create a new ticket, you consume project resources. Every bug report means money spent on the project: 1) money for your time spent finding the problem and reporting it; 2) for the time of the project manager who is working with the ticket and finding who will fix it; 3) for the time of the ticket solver, who is trying to understand your report and provide a solution; and also 4) for the time of everybody else who will participate in the discussion.
If you close the ticket without a problem being properly solved, you put this money into the trash bin. Once the ticket is started, there is no way back. We canât just say, âNah, ignore it; itâs not important anymore.â Your ticket already consumed project time and budget resources, and in order to turn them into something useful, you have to make sure that some solution is delivered.
It can be a temporary solution. It can be a single line change in the project documentation. It can be a TO-DO marker in the code saying that âwe are aware of the problem but wonât fix it because weâre lazy.â Anything would work, but not nothing.
Look at it from a different perspective. When you started that ticket, you had something in mind. Something was not right with the product. Thatâs why you reported a bug. If you close the ticket without anyone even touching that place of code, someone else will have the same concern in a few days or a few years. And then the project will have to pay again for a similar ticket or discussion of the same problem. Even if youâre convinced that the issue you found in the code is not really an issue, ask a ticket resolver to document it right in the source code in order to prevent such confusion from happening again in the future.
4. Avoid NoiseâAddress Your Comments
Every time you post a message to the ticket, address it to someone. Otherwise, if you post just because you want to express your opinion, your comments become communication noise. Remember, a ticket is a conversation between two peopleâone of them reported an issue and the other one is trying to fix it. Comments like, âHow about we try another approachâ or âI remember I had a similar issue some time agoâ are very annoying and distracting. Letâs be honest, nobody really needs or cares about âopinions.â All we need in a ticket is a solution(s).
If you think the ticket should be closed because the introduced solution is good enough, address your comment to the ticket reporter. And start it with â@jeff, I think the solution youâve got already is good enough, becauseâŚâ This way, you will help the assigned to close the ticket and move on.
If you think the solution is wrong, address your comment to the assignee of the ticket, starting with â@jeff, I believe your solution is not good enough becauseâŚâ This way, you will help the ticket reporter keep the ticket open until a proper solution comes up.
Again, donât pollute the air with generic opinions. Instead, be very specific and take sidesâyou either like the solution and want the ticket to be closed, or you donât like it and want the ticket to stay open. Everything in between is just making the situation more complex and isnât helping the project at all.
5. Report When It Is Broken
I think it is obvious, but I will reiterate: Every bug has to be reproducible. Every time you report a bug, you should explain how exactly the product is broken. Yes, it is your job to prove that the software doesnât work as intended, or is not documented properly, or doesnât satisfy the requirements, etc.
Every bug report should follow the same simple formula: âThis is what we have, this is what we should have instead, so fix it.â Every ticket, be it a bug, a task, a question, or a suggestion, should be formatted in this way. By submitting it, youâre asking the project to move from point A to point B. Something is not right at point A, and it will be much better for all of us to be at that point B. So itâs obvious that you have to explain where these points A and B are. It is highly desirable if you can explain how to get thereâhow to reproduce a problem and how to fix it.
Even when you have a question, you should also follow that format. If you have a question, it means the project documentation is not sufficient enough for you to find an answer there. This is what is broken. You should ask for a fix. So instead of reporting, âHow should I use class X?,â say something like, âThe current documentation is not complete; it doesnât explain how I should use class X. Please fix.â
If you canât explain how to get there, say so in the ticket: âI see that this class doesnât work as it should, but I donât know how to reproduce the problem and how to fix it.â This will give everybody a clear message that you are aware that your bug report is not perfect. The first step for its resolver will be to refine the problem and find a way to reproduce it. If such a replica canât be found, obviously your bug will be forced into closing.
Let me reiterate again: Every ticket is dragging the project from point A, where something is not right, to point B, where it is fixed. Your job, as a ticket reporter, is to draw that lineâclearly and explicitly.
