Introduction

As Tech Leads, it is our job to maintain a perspective on the entire system we’re responsible for. This means that we’re in a position to see the entire landscape. This in turn means we can often spot with confidence where a strategic change in the system can make things better.

Sometimes these realisations come quickly, sometimes they brew over days, weeks or months until the right way of dealing with the problem becomes clear.

While you’re still ruminating on the problem at a high level, it is reasonable to keep it in your head and chip away at the problem and experimenting with code. In amongst all your other responsibilities, maybe you’ll eventually get to a Pull Request. But will your team understand this thing that hasn’t been shared until that point? If you had shared it sooner, they would have been along for the journey. This particularly applies to newer and more junior members of the team.

At some point your understanding of the problem and the very general shape of the solution probably reached a point where you could have written a ticket to describe it. It’s at this point that we should think hard about whether to continue, or to communicate it to everyone else. Maybe you didn’t because there was too many possibilities, too much detail to distill and work to communicate - words are hard. Maybe you didn’t because you still want to be an individual contributor - which is difficult to balance as a Tech Lead. You should still get time to write code, but doing it by keeping things secret all the time isn’t healthy.

The larger a piece of work gets, the more complicated it is, the more specific knowledge is needed or developed. At this point, everyone would benefit from it being shared and the work can benefit from everyone’s knowledge and abilities.

My ticket writing guidelines

To help me break out of Just Doing The Thing, I have some guidelines and structure which I use to construct a ticket. Following them helps me to share and delegate with the team what I’ve started.

1. Talk about the problem, not your solution

This will help you understand the problem yourself, as well as communicating it to others.

Well-formed user stories should not talk about a solution, only what the user is able to do as a result. Otherwise it’s hard for anyone else to read it as anything but a done deal. The team might assume that because you’re the tech lead, you know best or, worse, you have decided that it will be as you decree and that you are not to be questioned.

As a leader, you need to walk the tightrope of providing direction versus sharing and delegating to your team. Tickets should not completely abstract a problem and the solution but they do need to provide enough guidance for a team member to solve it.

2. Every card should start with at least one user story

As part of talking about the problem and not the solution, you should try to express the problem in terms of user stories. This will help pull you back from the abyss of solutions. User stories are a great device for giving a different view on the problem you’re describing. This isn’t a hard rule because problems sometimes just don’t fit into user stories - infrastructure problems in particular.

3. Description

User stories are great, but they can’t describe a whole problem situation, trying to do so is impossible. Use a description to flesh out the detail of the problem.

4. Give context

Sometimes you need to give a wider context to an issue, especially if the part of the system is unfamiliar to some or all of the team.

5. Clearly identify things which you aren’t sure of

If you want to include something, but aren’t sure whether it’s true, say so. This should help with the feeling and pressure that you need to complete all the thoughts before you can write a ticket for it. Being openly honest about the limitations of your knowledge as a Tech Lead is a powerful tool to encourage your whole team to contribute - it’s important that everyone knows it’s OK not to know everything.

6. Think about your audience

The ticket needs to make sense to most people on your team. Do they all know about the technology, code or functionality in question? Will your product manager be able to understand and make decisions based upon the relevance and importance of the work?

7. Use a “Considerations” section for potential gotchas and things that need more thought

If I’ve seen potential gotchas or aspects which need considering, I’ll include them in a section called “Considerations”. This means you can delegate to your team or future-you the work of deciding whether or not they are an issue and how to overcome them.

8. Acceptance criteria

This is a concrete checklist of things which enable you to communicate what the solution needs to achieve, but not in terms of what the solution is in detail. Doing that can be very tricky, especially when the work is further away from the user, but getting better at this is essential to avoid boxing the reader in. Like user stories, they give the reader another view on the problem you’re describing.

Benefits

I think these guidelines are useful for all developers, but they are especially important for us as leaders. As a leader, you help define the culture by your behaviour. That means that you need to work in the way that you expect any team member to behave. This includes identifying and communicating potential work and using the workflow the team has for prioritising, discussing and doing work. By doing this, it keeps you honest and prevents you from working on whatever you feel like.

I find that thinking about the ticket as making it possible to delegate the work - either to my future self or to someone else - makes it easier to get started on. Writing the ticket helps me to let go of things I discovered or thought about but which turned out to be irrelevant and to crystallise all of my thoughts. Even if I continue working on the ticket straight away, it makes it easier to work on. Letting go of the problem in this way means that you can get on with your real job of helping the team do theirs.

By writing a ticket to describe the problem, you help your team in many ways:

  • you are sharing what you’ve learned
  • the product owner gets a chance to prioritise the work and to understand the problem you’ve discovered
  • you give the team the opportunity to understand and discuss the details, rationale, and significance of the work in team planning. They can also help to shape and improve the ticket. This is important for team cohesion and ownership as well for them to understand the background and rationale.
  • you give the opportunity for the team to work on the problem and the solution together
  • you make it much easier for someone else to pair on it with you as there’s a natural break and signal that they can join in

Conclusion

I’m not saying you can’t Just Do The Thing sometimes - I certainly do. I am saying that you and your team will be better off if you can get into the habit of sharing and delegating more often, rather than dropping a 1,000 line pull request from orbit.

I’m not saying you should write all tickets in this way - I certainly don’t. As you get more practice, it will get easier and you’ll develop intuition for how to write problem-focussed tickets, as well as when to break the rules and Just Do The Thing.