Writing Technical Considerations

About a year ago, my team lost one of our strongest developers. Not in a bad way, he just took on the Tech Lead (TL) role for another team. The gap that he left became abruptly clear. We started shipping things that were susceptible to not-so-edgy edge-cases, things that did not coincide with what our designer and Product Manager (PM) had envisioned, and code that was just plain bad quality.

The PM and I soon realised that we needed to address this problem. And fast. We came up with something that we call Technical Considerations.

Simply put (and without making it sound too waterfally), this is a document that outlines the approach that the developers will take to implement a feature.

But first, some context

Our team has a structured way of working. We have a set of ambitious OKRs that we want to reach — basically, a metric is below a certain threshold, and we aim to get it above that threshold.

To improve these metrics, we take on a various number of “bets” — initiatives and features that we bet will move a specific metric in the desired direction.

At Relive, we are incredibly product-focused, and we ship on a weekly basis. As such, we have to move fast — which inevitably leads to some roles overlapping. In particular, this means that engineers can make product decisions (improving on the copy of the design, displaying correct error messages, etc.).

Consequently, anyone can write a bet. In our case, these are mostly produced by the PM and designer.

This fast pace means that we cannot afford to spend the time to write elaborate Product and Engineering Requirement Documents.

We needed a way to quickly identify the potential shortcomings and pitfalls in testing a hypothesis. A single document where we could align on the technicalities and intricacies of a bet, where developers could even identify how a hypothesis could be validated faster.

And thus, Technical Considerations were born…

Common symptoms

How do you know whether routinely writing technical considerations is something that you and your team might benefit from? If you are frequently running into things like:

• Bugs discovered in production
• Rabbit holes causing the feature build time to take much longer than expected
• The implemented feature is not what the PM (or designer even) had in mind

Then I urge you to give technical considerations a shot at solving, or at least minimising these symptoms. Keep in mind, that the above is not an exhaustive list.

There is a lot to gain if the knowledge gap between the PM and TL can be bridged, such as addressing the following:

• Over-expectation from the PM and under-deliverance of the developers.
• Wasted time due to over-speccing, or speccing things that fall outside of the scope
• Misalignment on the project goals

How often should I write Technical Considerations?

Ideally, one document detailing the Technical Considerations for every bet. Some technical considerations will be short, others, much longer and much more detailed. It all depends on the bet, so use your judgement here.

What does Technical Considerations look like?

In the agile-like world that we live in, writing has become associated with the sinful practice of waterfall. However, I’m of strong believe that developers write too little, and code too much. A little bit of pre-emptive writing leads to less (and much more maintainable) code since it forces you to give some thought to the code that you will be writing.

Technical Considerations form part of a bet, so it does not exist in isolation. I’m not diving into the details of what a bet should contain here, but in short, a bet generally describes a hypothesis and the motivation for that hypothesis.

Below, I describe some headings that your Technical Considerations document should have.

Implementation

Describe the approach that you want to take when implementing this bet.

This should not be technical. The PM should be able to read this and understand the approaches that the developers will be taking in implementing this bet.

On the other hand, the developers should be able to read this and have a very clear picture of the abstract implementation that lies ahead.

Quality

How are you going to ensure that the bet’s implementation is performing as expected once it goes live?

This gives a clear understanding of the types of monitoring that is in place so that your team can be confident that the bet is running as expected. Bonus if this further gives you insight into how the bet is performing.

How much will it cost?

Any additional costs that this may cause?

Check this twice. This section is especially relevant when using external services. Ensure that you understand the pricing model and that you can give a decent estimate on the usage that the implementation of the bet will incur.

What are the limitations or tradeoffs?

What are some sacrifices that you will be making?

Is this a quick and dirty implementation to proof of concept? Be sure that everyone is aware of the tradeoff that this leads to — you’ll be running into some hard-to-maintain code if you don't allocate some time after the proof of concept to refactor the implementation in a cleaner way.

What are the alternatives?

What other approaches did you consider?

No problem has a single solution. This is the section where you elaborate on the alternatives that you considered, and why those alternatives are not being considered over the approach that you described in the “Implementation” segment.

Conclusion

Writing Technical Considerations is certainly not a silver bullet that will solve all of the problems that your team is experiencing. But it most certainly helped our team get back into our groove — over the last 6 months, we’ve successfully shipped more than 35 bets and experiments with this approach.

The structure that I present here works for us. Surely you will evolve into a structure that works for your team — so play around with this, and discover a structure that works for you.

Lastly, writing Technical Considerations should not be something that is limited to the TL only. It’s a wonderful tool that developers should also employ (especially juniors) that can enhance their architectural skills and abstract design abilities.

We’re hiring

The above experience I got from working at Relive. We’re looking for people to help us grow to the biggest outdoor platform there is! Keen for a challenge? Join us at jobs.relive.cc.