How, Why, and When: The Elements of an Effective Ticket Comment

At Revelry, we are always trying out new processes and refining old ones. We have a whole Slack channel dedicated to discussing #process and finding other, better ways to do something that will benefit everyone. And recently, I decided we needed to place a bigger emphasis on ticket comments.

This decision didn’t come out of no where. And let me be clear – we practice good communication skills on our team, and that shows in our project updates and our GitHub Issues comments. But it’s good to look in the mirror every now and then to reassess that you’re doing the best job. Try these practices out on your team – and discuss the reasons why – and let me know what you find out.

I’m going to jump right in and share the elements that create an effective ticket comment.

HOW to write an effective ticket comment:

• Start with context. Restate the task as you understand it, and explain how you’re going to work on the task. Give updates on the current state of the implementation progress. Share what you’re doing and what you’ve done.
  • Briefly explain the work you have accomplished since your last ticket comment
  • State what work is left to do
  • Call out (brief/bulleted) implementation plan (ok to tag lead developer)
  • “Note to self” for next time you pick up this ticket (particularly helpful on Fridays)
  • Call out any potential risks, blockers, or questions

• Raise questions and challenges in a helpful way. Use Issue tagging if available (the Question tag is a helpful one.)
  • Ask yes or no questions. Make sure your question doesn’t get lost. Help your respondent find and reply to your questions faster.
  • Explain where you’re coming from. State your perception of the current problem and your proposed solution. This way, your respondent can meet you where you are.
  • Number your questions. This keeps the answers crystal clear: your respondent can number their answers accordingly.
  • Tag your teammate. Tag the appropriate teammate or product owner’s GitHub username in your comment so they can zoom in on exactly the right comment.
  • Assign the ticket. Assign the ticket to the individual(s) who need to take the next action, whether it’s answering your questions or performing another task.
  • Bonus: ping teammates in Slack. Depending on how your Slack integrations and project channels are set up,  this may help to ensure that the ask isn’t buried. Just give them a heads-up that the ticket’s been placed in their court.

• Help cross-department teams: Give information to the next assignee on your ticket.
  • Include testing notes if you’re passing this to the QA team or product owner.
  • Bonus: Explain any additional caveats or context. There may be other related tickets in progress that should be checked out.

Honestly, I think this is a great reminder for tailoring and tweaking all forms of communication. But let me share with you how we formed these ticket comment qualities. As I mentioned, it’s all about examining your processes. So, let’s move on to the why.

WHY it’s important to put extra effort into your ticket comments:

Processes are negotiable.

Everything is negotiable, and the Revelry processes are no exception. Everyone’s input is welcomed and valued, particularly if they have a strong case or rationale for recommending a change.

On a lean agile team, decisions and new processes can be implemented in a matter of minutes. We’ve held a morning standup on Slack every day on every project for longer than anyone can remember.

And about a year ago, we added an end-of-day check-in. We called it the 4:20. Each project channel alerted the team with a reminder: comment within the thread about your progress for the day, and your evaluation of the health of the overall sprint.

We debated, challenged, and changed the phrasing of this reminder as we iterated on the 4:20.

Processes can be abandoned.

So, sure, the 2.5 to 4 teammates resourced to that project that week would chime in on their 4:20. But we saw a problem: even with full team transparency across all of our projects (all of Revelry can read, review, and choose to comment on any Slack channel), information captured in daily 4:20s aren’t necessarily shared or acknowledged by the rest of the team.

So we killed the 4:20.

Collecting data improves process decisions

We didn’t kill it with fire right away. We decided to pause the practice for two weeks in order to collect information on how we could make our ticket comments even better.

Since we track our work on GitHub Issues, we keep an active thread of comments on each ticket. If team members write their comments well, everyone will be in the loop on task progress. It’s a particularly great way to keep the PM and the product owner involved. And, the code and design work happening throughout the day is completely transparent.

But, there are so many methods and moments to write a ticket comment that we don’t always think of.

We could still do better.

Agree on the elements that form good ticket comments.

The project management team asking, poking, nudging, and prodding the team along for ticket updates was only sort of helpful, and only garnered responses 50% of the time.

I wrote up a guide and submitted an entry into our team wiki. In it, I detail not only when and how to write ticket comments, but also why we write ticket comments in the first place.

Be excellent to each other.

The first and foremost reason we write ticket comments is so that we can follow our golden rule: Be Excellent To Each Other. Helping each other to understand projects and do our best work is a big part of that.

Suffering in silence isn’t a sign of strength. We highly encourage all types of questions, pair programming, or any type of pairing in general that will work best for teammates.

Swap team resources.

We plan ahead for vacations, but life happens. There are times when you have to drop what you’re doing and take time off. Other team members need to know where you left off, so they can continue the work without duplicating efforts.

This also allows for your peace of mind when you do take a trip. It’s pretty great to be able to leave your laptop behind when you go on vacation. When you’ve already spelled everything out that you know, you can rest assured that you’ve covered more than one of our Core Values: Earn and Dispense Trust, Work-Life Alliance, and of course that good old Being Excellent thing.

Create transparency.

A Revelry motto is transparency: we want to give our product owners and innovation partners as much insight to our work as possible.

Even if we do have an internal conversation about the project, we document the result of that conversation in a ticket comment. This gives the client confidence that we are continuously working and problem-solving.

When a developer calls their shot on a ticket, they provide insight into how they view the Acceptance Criteria and the overall problem. This creates a space for the PM to jump in if something sounds off from their interpretation. Even the most well-intended user stories can be subjective, after all.

And of course, WHEN you submit ticket comments matters, too.

I could say that there is no such thing as a wrong time or too many comments on a ticket, but having guidelines helps every member of the team. Here are the most critical times that warrant a ticket comment because they will provide the most value.

• After picking up a new feature ticket: Comment within 1-4 hours after starting your task. What have you found? What have you done? What are you going to do? Call out your shot.
• You’ve got to pause: Just say so. Pausing here for the day. Pausing here for a bit.
• On progress milestones: Pull Request submitted. Moved to QA or User Testing. Deployed a feature. Merged a PR.
• New information received: In-person meetings (or the virtual world’s version of them: Slack and Zoom conversations) can affect the work you’re doing. If a decision that happens outside of the ticket affects your work, or affects the ticket’s Acceptance Criteria. document the decision in a ticket comment. And, update the AC to reflect the current truth.
• Your work affects another ticket: When the progress you make on the ticket you’re working affects a ticket someone else is working on, mention that ticket and be diligent with your updates.
• You’re blocked: When you’ve been struggling for over an hour, and have made no progress, update your ticket. Again, it’s not helpful to suffer in silence.
• 24 hours have passed: If none of the above situations have occurred, give a ticket comment that’s akin to a hand-wave. Tell the team what you’re doing now.
• You’re not blocked, but something feels weird: Raise the flag. Make the smoke detector beep. If something doesn’t sound or feel right, say something in a ticket comment.

 

It’s time to up your comment writing game.

When everyone understands why ticket comments are so important to a successful project, I’m hoping that we’ll all be more willing to up our ticket comment game.

Plus, if we’re going to question everything, we may as well start with the root of how this process of leaving ticket comments came to be.

I hope this helps make you a more effective communicator on your teams. As a PM, communication is so critical to my success, my team’s success, and my clients’ successes. So I intend to continually improve my communication skills and educate others to do so as well. This helps me smell smoke earlier and keep expectations aligned and projects successfully.

Let me know: got any tips to keep project communication open and clear? Have these methods helped you?

---

Communication Product Management Productivity Project Management Team Communication Transparency