What does a good Tech Vision doc look like?

Question

I am about to start writing a multi year/multi quarter Tech vision doc for my org. To give a bit of background, my org contains 4 teams (1 front end team, 3 backend teams). All 3 backend teams (~20 engineers) work on a big monolithic service containing around 40 different APIs. Of the 3 backend teams, 2 of them work on Product features and the 3rd team (my team) is the Platform team which works on clearing tech debt, architectural enhancements, migrations, etc. For the last few quarters, the entire Platform team has been working mostly on clearing tech debt added by Product teams. The product team engineers have a very tight deadline, so their designs and code are bad or not well thought through.

My vision is basically to split the monolithic service into 3 services with clear separation of concerns and let the product teams be in charge of their own destiny. The reasoning behind this is that I feel like Platform team has been stuck in a perpetual cycle fixing bad work done by Product teams. There is no time for Platform team to enhance the capabilities of the platform. I spoke about this to my manager and he is very excited for me to come up with a vision doc and offered whatever support I would need.

So, given the context, I have the following questions:

What does a good tech vision doc look like? What sections should it have? Currently, I have the following sections: Motivation, Future Architecture (Splitting the Service), Deploying in the new world, Automated end - end tests in the new world (we don't have end - end tests currently)
How do I "sell" this vision to my management chain (my manager is onboard with the general high level idea), Principal Engineers, Product engineers in my org? I know the Product engineers are not gonna like the monolithic service to be split and will push back. How can I convince them?
What pitfalls should I be aware of while doing this work?
What upfront legwork can I do before I present this doc to everyone?

Appreciate your help in advance!!

Jordan Cutler · Accepted Answer

Love this question and I definitely have some good resources and advice for you. I'm also looking forward to hearing others chime in, especially the more senior people.

What does a good tech vision doc look like?

This, I will say I have less experience in, but, thinking at a high-level, it doesn't seem super important.

The main thing I'd say is from a writing perspective, think about 2 things:

Who is your audience? - It seems like this is management, engineers, principal engineers, etc.
What is the goal of you sharing this with them? - It seems like this is "Ensuring everyone is on the same page about a technical direction" but you have the most context here.

Once you have the answer to these 2 questions, write the doc with that in mind.

Organize it however you want. As long as it is in service of the goal. Don't add unnecessary stuff that is not needed for the goal.

Now, with this high level advice in mind, I do understand the root of your question is more about: "From experience, what works as a technical vision doc?"

I have these resources that might be helpful to use for some ideas:

How do I "sell" this vision? & What upfront legwork can I do before I present this doc to everyone?

Understand everyone's incentives. Identify how you can align and make them want what you are proposing.

Managers: What will be the delta between existing and new system? How will engineers be able to make more impact. Managers get promoted through…
- Their team should deliver on the key features and outcomes for the business.
- The manager recruits and retains the correct engineers on the team.
- The manager coaches and grows high-potential employees, and removes low performers before they cause too much damage.
- The manager collaborates with other teams to identify potential issues or opportunities.
- The manager contributes to the strategy and roadmap for their team and broader org.
Senior eng: Less stress, ship projects faster, opportunity to show technical depth
Junior eng: Show signal for promotion, ship projects faster, less stress, learning opportunities

(taken from the presentation on revamping on-call processes: https://www.jointaro.com/event/revamping-oncall-for-20-instagram-engineers-senior-to-staff-project/ highly recommended viewing for your question)

The upfront legwork you do will help you sell much easier. Schedule 1-1s with the people you know will disagree with you. Work on it with them. Ask for their advice but also explain why you think a particular way will be better in their language by making a case for their incentives. You might not be able to 100% do this, and this is why for those cases I'd recommend also 1-1ing with people that would be in the middle or on your side to get further buy-in, so you have an overwhelming majority in your favor before the meeting.

What pitfalls should I be aware of while doing this work?

The main pitfall to be aware of in my opinion would be thinking about it from your perspective instead of everyone else's. Realistically, you are introducing a large change to maybe 30-50+ people for the next year or so. That's a big deal. You shouldn't go into it thinking, "I need everyone to agree to my proposal." It should be, "How can we come to a solution together that most people would agree will leave us better off in 1+ years"

By the way, I'm not saying you were thinking of it like the former, just wanted to answer your question about a common pitfall.

I hope this helps and best of luck! It seems like this is a really awesome learning opportunity.

Also, shameless self-promotion: I share advice on my newsletter here and your question actually inspires me to make a post about this in the future. Maybe I can combine some of the other advice you receive on this and attribute it. https://careercutler.substack.com/

What does a good Tech Vision doc look like?

Discussion