In my time at a Big Tech Company, I was the Technical Lead for an internal DevEx tool, Engineering Insights. Over two and a half years our team developed a data application that provided actionable software engineering metrics relating to software delivery, reliability, and security of the services that engineering teams developed and ran. We had a joke metric that wasn’t on the dashboard – Mean Time to Re-org (The real MTTR). During my tenure of five years at the company, a large-scale reorg that impacted engineering teams would happen, on average, every twelve months. At best this was shuffling existing teams and management layers; at worst it was the tech layoffs of 2022/23.
My anecdotes data showed that three months after every major reorg, there would be a smaller-scale reorg. These tended to address the realities of doing more with less and would simply Ctrl+Z some of the changes that were announced months earlier.
As a tech lead of a project, these reorgs led to frequent changes in management reporting lines. The twice-annual reporting line change drew my time away from the team and project, and was spent on understanding the positions and intent of the new management structure, and briefing them on the work we did and why it was valuable. Engineering metrics, like any product, has a lot of nuance to it. Folks new to the project who only did surface level due diligence would misunderstand the details rather than fail to grok them in the first place. When a new hire joins the company there’s an expectation of some number of months before they develop expertise in all of the in-house systems. When there’s a reorg there’s an expectation that the new manager of an area is effective overnight.
The frequency of these reorgs and the role I had at the time contributed to me eventually leaving the company. I found I was spending x months a year focusing on dealing with org structural changes. David Graeber’s Bullshit Jobs strongly resonated.
As the reorgs rolled, I learned that in order to preserve my time for the team and project I needed to improve the speed at which new people (particularly management) onboarded onto Engineering Insights. I did this through writing and documentation. We had in-depth docs for users of our product. We also had a roadmap that, painful to realise in retrospect, got the most discussion at the time of every reorg. Over time I learned that essentially writing context and documentation about the roadmap greatly benefited the onboarding of new managers, engineers in the area, and curious customers.
The ‘what to actually write’ here is squishy and will depend on the context of your organisation, team, and domain. For us, in the world of engineering metrics, almost every new starter would pitch their favourite engineering metric and encourage us to measure it. I found that writing one-pagers on metrics we weren’t measuring (Mean Time to Recovery, Change Failure Rate, JIRA metrics, etc..) shortcutted weeks-long conversations. More generally, I altered my writing style for the more advanced docs by including information and context that would be relevant to someone yet to start in the team.
Documenting the roadmap acts as a resilience measure against reorgs. All teams have a visible roadmap and implicit understanding of the value behind the work they are doing. Making this value, and the decisions around it, explicit through documentation sets a status quo for new joiners (whether management or not) to understand the work that has been done and the work that is coming up. It acts to minimise the turbulence that reorgs impose on teams and their projects.
