During my time at madewithlove, I got access to one of our clients’ really extensive Notion workspace. While the amount of documentation was impressive, I soon noticed they had numerous similar pages spread over different parts of their wiki. I dug deeper and found even more pages and subpages, which only confirmed the feeling I had. I checked who the creators of these pages were and asked them when & why they started those pages and started seeing a pattern.
At the time, I was trying to gather an overview of all the documented technical debt they had. Each of the pages I found contained either a plain-text list or a database of technical debt. There was an old one that seemed severely outdated. There were a few lists spread across the guilds (the team used front-end and back-end guilds to organize initiatives that span multiple teams and are very technology-specific, inspired by what Spotify introduced). There was a really extensive “wall of technical debt” where the team had assessed the effort & impact for each of the initiatives (but went no further than that). There was a research section that had elaborate documentation on specific technical analysis, often but not always related to features on the roadmap. Finally, there was a “bets” database that had just one entry, which was just a problem description and nothing else. Whenever I see this happening, it's often due to either a lack of communication or the inability to turn things into concrete actions.
Regardless of the reason, it's never bad to start consolidating and cleaning up. I was about to throw away the last one when I noticed it was the most recent of all of them. I reached out to the person who started it, and they told me it was an idea of their former CTO to tackle technical debt in a new way. Jokingly, I said: oh, so you made a mess of the wall of technical debt, so they just started over somewhere else like nomads do (“digital nomad” suddenly sounds a lot less cool now)? We laughed a bit, but the conclusion was that this was precisely what had happened, and not for the first time too.
Every time the team became discouraged about the list just growing longer and their inability to tackle anything on it, they'd just start a new list. Like building a V2. But just like building a V2 doesn't make your V1 go away, the tech debt doesn’t go away either. You end up just slowly creating the same list over again until you move on to the next one.
So together with the team (thanks, Notion, for clarifying who created/maintained a page), we started removing all the lists in favour of the one that had the most mature shape. We either remove pages, or moved them under the “wall of technical debt”. With that preparation out of the way, the next phase was a team meeting to go over everything on that list and ask ourselves a few questions:
Is this still an issue? Will it make any impact and, if so, how big of an impact? If the impact is low, is it at least so small we can do it in an hour and get it over with? If the potential impact is a bug, how can we measure or prove that? And how much work will it be? If it requires significant effort, can we deliver something that will already provide us value early on and take us a step in the right direction?
The goal of this exercise was to select a few candidates where everyone (or most of the team) could get themselves behind. Things they deemed important. We would then start working on a more extensive document that would describe why the topic was so critical, and what would happen if we didn’t address it in a timely manner. We would add metrics (bugs, customer support tickets, performance metrics, post-mortem documents, sometimes time tracking data) to further argument. Finally, we’d list some options we could pursue, our option of choice (and the argumentation behind that choice), and a high-level plan of action on how we intended to tackle it.
With some well-researched candidates underneath our belt, we’d be well-equipped to pitch these to management. From there onward, our roadmap would become more balanced between feature-work and technical improvements.
