Clear technical vision is the key for aligned growth

Estimated reading time: 9 minutes

As engineering organizations grow and the cost of coordinating goes up, scalable tools for creating alignment are increasingly important. 

One of the most valuable tools for scaling and alignment is a technical vision: a document that delivers a shared framework for decision-making. One of its biggest advantages is that it provides guidance without the need for direct, high-touch interactions, like code reviews, that don’t scale. 

A strong technical vision will succeed in supporting long-term velocity and flexibility, but it can only work if it’s compelling: timely, useful, opinionated, and memorable. Expect to create several iterations and drafts, to test both the substance and the wording, and to seek out feedback from a variety of sources.

What is a technical vision?

A technical vision is a document that describes how your organization wants to build software and solve problems over the next few years. Technical visions have the blessing of leadership to be used as guides for decision-making when there are multiple good options, so that everyone works toward the same goal. 

Technical visions can apply at different scales. A whole engineering organization may have a technical vision that addresses high-level architectural questions – microservices over monoliths, continuous delivery over large change batches, eventual consistency over strong consistency, etc. Engineers may also create technical visions for projects or subsystems that address more specific choices like using a particular library for testing or HTTP, adopting an architectural pattern like model-view-controller (MVC), etc.

Engineers can reference the document when justifying choices, or challenge each other questions when an architectural design doesn’t align with the guidelines. As a result, people who are not working together will make decisions that are aligned with the vision, and so aligned with each other.

At an organizational level, technical visions create interoperability that makes it easier to change directions in the future. When systems are built in a shared, consistent way people can  join new teams, change ownership of software, and even reorganize entire organizations smoothly. It also allows for easier recomposition to build new kinds of products and features, because the designs will be compatible.

Do you need a technical vision?

Technical visions are powerful tools for alignment, but that does not make them a solution to all problems. No matter how well-crafted, if the technical vision does not address a need in your engineering org, you will struggle to gain support for the project and the vision itself.

Small teams with high communication bandwidth generally do not need to write down a technical vision document: they can maintain alignment through conversations and other high-touch interactions. The same goes for early-stage teams, like those that are still finding a product-market fit, who have higher priorities than investing in long-term flexibility.

Unlike smaller companies, technical vision documents can be extremely useful to larger, established organizations that have outgrown their old communication structures. Engineers in this environment are often encouraged to pursue aligned autonomy in other ways, while still needing to iterate and innovate.

Start from where you are

A candid, blameless assessment of the current state of the organization and its software is critical to building a compelling technical vision. To appeal to engineers, the vision must address real challenges teams are facing, and build from what is true. To appeal to leadership, the vision must support the business’s strategy.

When you talk to people across the org, take note of patterns. This can be complaints, engineers across multiple teams solving similar problems, or engineers spending too much time on low-leverage work. Find projects that have stalled, failed, or even just taken longer than you would expect, and look for common issues. Points of friction that slow down day-to-day development across teams are a good place to start, for example, slow or flaky tests, complex interdependencies, and contention for shared resources.

Another area to investigate is those that incite engineer uncertainty or confusion, leading them to take too long to make decisions. It can show up as teams using outdated or ineffective methods simply because no one feels able to change them: some past attempts to improve might have failed, or perhaps they do not have the time, authority, or confidence to try to build consensus around a new approach.

Create goals for the vision

Once you have a diagnosis of the current state, identify the problems you would like a technical vision to solve. When building out the goals of your technical vision, it’s important to prioritize only the most important transformations for the company’s technology. Try to avoid the temptation of throwing a wide net to achieve everything at once. Instead, focus on how you want it to evolve across the next two to five years.

At Policygenius, our diagnosis showed that we had a pattern of building too many similar and overly specific tools, which we could not reuse, causing a vicious cycle. Additionally, our previous attempts to break apart our monolithic application had only created a distributed monolith that was a challenge for scaling and reliability. To attack the problem, we pulled together a tech vision that was underpinned by six goals:

1. Clarify responsibility and ownership boundaries. We wanted teams to have a clear relationship to systems so they can build and share expertise, and foster a sense of ownership.
2. Enable aligned, autonomous teams. We encouraged teams to focus on alignment, interfaces, and interoperability so teams can work independently with less risk of churn around integration points.
3. Build for 10x scale. We didn’t want to over-invest in the far future, while also not letting technology be a barrier to near-term growth.
4. Spend the majority of our time creating value. We gave teams a target for how much time they should be spending on work that created business value over limiting maintenance and toil.
5. Maintain our high pace of delivery. We had invested in a culture of continuous deployment and rapid delivery, and wanted to maintain that.
6. Define and maintain service level objectives (SLOs). We wanted to be able to effectively measure, and tell stories about, how our incident response was improving.

Ground the vision in existing work

With a diagnosis and goals in hand, it is time to start working on the technical vision itself. A good place to start is by looking at the work teams have already done that is worth scaling up to the whole org. The vision will be more compelling if you can show how aspects of it have already been working. And by building on and promoting the work of teams, you leverage their enthusiasm and expertise.

For example, at Policygenius, we had identified that teams were rebuilding the same internal APIs instead of reusing them. One team had already explored better options using OpenAPI and protocol buffers to improve API definitions. Their research had shown there was potential to improve the design and discoverability of internal APIs, which would encourage reusing them. They chose to use protocol buffers for internal APIs going forward. We adopted this choice as part of the vision, leaning on their work to justify the decision, and scaling their impact to the entire org.

Focus on trade-offs

These are our specific choices. Other choices are potentially valid, but they’re not the ones we’re making. When we make these choices, we know we are making certain trade-offs, but think these are the right ones for us right now. – Policygenius’ technical vision, 2021

Decisions in a technical vision are only helpful if they address real points of disagreement or bad habits. For example, adding a goal into the tech vision document stating that your team should “test their code” is pointless if they already do it consistently. But if your team is only just starting to build the habit, it can be a valuable reminder. 

Similarly, if teams are always debating on whether they should add new features to an existing system or create a new one, having a visible goal of “we are committed to improving our existing system,” can give them a clear direction. 

The decisions engineers make day-to-day depend on different factors like the stage of the company, team maturity level, languages and ecosystems, and others. Clear, guiding statements can help them evaluate how to move forward with these factors in mind. For example, at Policygenius, our use of languages like Ruby and JavaScript led to a bad habit of passing along data until an error occurred, instead of validating proactively. To fix this, we created a new guideline in our technical vision: “handle errors proactively,” which encouraged teams to address issues much sooner. 

We found that our goals for the technical vision helped teams prioritize workload better.  When a bug caused one of our services to receive over 100x its normal load and crash, the team decided that making it more robust was not a priority. Our vision’s goal was to have it handle 10x its normal load, and it had done that just fine.

Wordsmith and revise

Writing out a technical vision should take time. Write, revise, wordsmith, gather feedback, revise again, until you have statements or headings that are short, opinionated, and even pithy. Statements like “handle errors proactively” or “invest in the monolith,” are shortcuts for bigger ideas. They act as mental reminders that engineers can use while writing and reviewing code or making design decisions. Consider including explanations, examples, and other material that help clarify and remove ambiguity.

Ask engineers across a variety of teams and experience levels for their feedback. The technical vision needs to be comprehensible and useful to its entire audience, whether that is the entire engineering org or a part of it. And having their feedback heard and incorporated into the vision brings them in as collaborators. This helps build buy-in, which can turn them into promoters when it comes time to roll out the vision.

Rolling out the vision

To make your technical vision a success, start communicating with the org about it as early as possible. Let people know that you will be reaching out, asking questions, and reading technical designs and pull requests (PRs). Instead of surprising everyone with a finished plan, bring them along on the journey so they feel a sense of ownership.

Once the initial version of the technical vision is done, plan to keep promoting it. Work with your group of early promoters – the folks who have been collaborating and are already bought in – to carry the torch. Empower them to ask questions when reviewing code or designs that don’t seem aligned with the vision. This ensures that deviations from the vision are deliberate, not accidental. 

Celebrate moments when the vision helps a team or a colleague choose a path that is aligned with the org’s goals. As these become more frequent and the vision starts to become a part of the process, you can start thinking about the next revision.

Final thoughts 

Technical visions are compelling when they address real, timely needs, are built on proven work, and are memorable enough to serve as day-to-day decision guides. As technical leaders, staff+ engineers are uniquely positioned to draw the connections necessary to meeting these requirements. Achieving all of them is hard work and requires collaboration and willingness to pivot and revise. In exchange, you can have a massive impact on setting your org up for long-term growth and success.

Get articles like this in your inbox

Choose your LeadDev newsletters to subscribe to.