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:
Appreciate your help in advance!!
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.
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:
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:
(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 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/