Get a strategic vision of your technical debt

In the previous post, I presented an approach to manage technical debt on a daily basis in a team. But once in a while, we need to take a step back and get a higher-level vision of our technical quality. To do so we built a simple workshop that provided us very useful insights in several teams at Doctolib.

What is key here is to have everyone aware about technical debt, even non-technical people:

For a component that appears to be working, a non-programmer will assume the technical debt is minimal, or nonexistent. Colin Breck, 2016

The purpose is to identify technical risks in order to:

• Build an easily shareable high level vision of the team’s scope’s tech state.
• Have a better anticipation in features delivery: identify risky projects, identify refactoring to do along with features.
• Identify subjects for the team’s technical tasks roadmap.

We evaluate both Tech and Product scores for all components in the team’s scope using the following steps:

1. 🗺 Draw a map of the components
2. 🔩 Tech score: score technical quality & Identify existing issues
3. 💵 Product score: evaluate product criticality and feature needs
4. 🎯 Identify needs for investment, prioritize

This workshop takes 2 to 3 hours for the first time, less for the next occurrences.

Here is an example output for a fictional Veterinary health application:

Identified issues & Tech scoring mindmap

Scores overview

1. 🗺 Draw a map of your team scope’s components

These components are those owned by the team and/or with which the team works regularly. How many components should a team own really will depend on the team, but components should all be at quite a high level of abstraction and understandable from a product point of view. Most teams shouldn’t end with more than 5–6 high level components or maybe you have another issue and are in charge of too many​​ scopes.

When we didn’t have this list yet, we started from the product by using a Product Breakdown document, and also from the code using ownership files (e.g. CODEOWNERS). You can also take some time to identify better your business domain(s) and the corresponding bounded contexts.

We can now initiate a mindmap of all components, then have a quick discussion with the team, including the Product Manager, in order to make sure everyone understands and agrees on the split of the scope. This can be prepared ahead of the workshop, but make sure the discussion happens if the team never had such one about its overall scope. Also what is important is to focus not only the current scope but also any existing legacy in maintenance mode.

2. 🔩 Tech score: Identify existing issues & score technical quality

Tech Score = average(Ownership,Code,Tests,Other)

1. Identify technical issues for each component and by categories.
2. Evaluate Tech score by categories:

• Level of ownership : Are we used to working on the underlying code, do we understand well how it works?
• Code quality : Reliable, Performant, Readable, Easy to maintain
• Tests quality : Coverage, Readable, Stable
• Other known issues : various other topics, infrastructure, performance, recurring bugs, etc. (⚠️ Do not put product issues / missing features here, we’re evaluating technical quality)

We use a scale from 1 (very bad) to 4 (which doesn’t mean it has to be perfect, just that no major issue was identified).

NB: we didn’t use more dedicated categories in order to keep it simple, and also because the teams mostly focus on changing code (and not infrastructure for instance)

How?

We organize a brainstorm session during which everyone fills the mindmap with identified issues then votes for a Tech score for each category.

• If you don’t have a backlog of identified issues, you can organize a dedicated session to initialize it. Or maybe you should first start by using an approach to manage technical debt on a daily basis, see our previous post.
• If you have one, it’s still a good opportunity to organize a brainstorming in order to get the global vision & categorize issues: taking a step back will help to evaluate the score.

Then we have a discussion, component by component, to align on existing issues (⚠️ it’s not the time to discuss solutions) and the score for each category. Here the most important isn’t to have a precise score but rather a shared vision on the current state.

3. 💵 Product score: evaluate product criticality and feature needs

Product score = Sum(Criticality + Upcoming features)

Criticality: is this set of features critical? We used the following ratings:

• 0: Major issues can be fixed with regular bug workflow
• 1: Major issues resolution can wait a few days
• 2: We need to start a crisis (production incident) if the feature is not working

Upcoming features: are there major evolutions needed/planned in the next 2 quarters ?

• 0: Nothing
• 1: It should happen within 6 months
• 2: Major features are planned for next quarter

At this step and the next one it’s key to have the Product Manager in the discussion to have their input.

4. 🎯 Identify needs for investment, prioritize

Debt Level = Product score - Tech score

The highest scores have the most negative impact.

Now we have the big picture of our team’s technical debt, we can elaborate some decisions:

• Components with High debt and features upcoming soon: the team will work on these components soon and it will be risky and/or it will come with a higher cost. Let’s figure out during project scoping how much time we need to dedicate to improving quality as we pass on this part of the product.
• Critical components with High debt level but no new feature planned: these components didn’t change much but aren’t stable in production. We have bugs, incidents and it’s hard to work on this part of the product: let’s consider adding a project in our Technical Tasks roadmap.
• Components with poor Tech score but also low Product score have a low priority: don’t refactor code that works and doesn’t need to change.

For instance, the next quarter roadmap for our veterinary app could be impacted like that:

We’ll plan to refactor our availability service and fix performance issues while working on our Booking V3 project

During the next quarter we’ll dedicate 75% of our Technical Tasks to improve monitoring of the booking, and 25% to cover untested scenarios in the FAQ.

We won’t invest anything on improving the call center as it’s not critical and we currently don’t have any major issue with it.

Takeaways

This workshop has been used so far in several teams with some valuable outcomes and interesting feedback:

• Such a high level of discussion as a team helped to build a shared overview of the team’s scope, especially on legacy code or parts known only by some members in the team.
• It also helped identify priorities from a higher perspective than just having a Tech Debt backlog made of isolated tasks and to adapt roadmaps.
• Such a workshop isn’t adapted for a team who has mostly a legacy scope they don’t know yet. It would be better to start identifying technical debt along the way (or do an audit if you really need it now)

To go further you can have a look at a similar approach called Quality views brought by Colin Breck.

If you want more technical news, follow our journey through our docto-tech-life newsletter.

And if you want to join us in scaling a high traffic website and transforming the healthcare system, we are hiring talented developers to grow our tech and product team in France and Germany, feel free to have a look at the open positions.