Technical Vision Vocabulary

A technical vision document provides the "north star" for hundreds of daily engineering decisions — without it, each decision is made locally without a shared direction, and the architecture drifts rather than evolves intentionally.

The document typically includes: (1) The current state — an honest assessment of where the architecture is today, including known pain points; (2) The target state — a narrative and/or diagram of the desired architecture in 3 years; (3) The principles — the architectural values that should guide decisions (e.g., "prefer simple over clever", "all external communication is async"); (4) The key initiatives — the major strategic investments needed to close the gap between current and target state. The document should not list every engineering task — that belongs in roadmaps and backlogs. It should be short enough to be read and remembered (2-5 pages) and compelling enough to inspire.

Key vocabulary:
• technical vision — a description of the desired future state of a system's architecture and technical capabilities
• north star — a guiding goal or direction that orients decisions without prescribing every step
• architectural principles — the values and guidelines that govern technology decisions across the organisation

Vision statements are technology-agnostic descriptions of desired capabilities and properties — they remain valid even as the specific technologies and approaches evolve, providing stable direction across multiple planning cycles.

The distinction matters for decision-making: if the vision says "all services should be independently deployable," then when evaluating two architecture options, the team asks "which option moves us toward independent deployability?" — and the vision guides the choice without prescribing the technology. If the vision had said "we will use Kubernetes," it would need to be rewritten every time a better tool emerged. Will Wright (game designer) described this as the difference between "the game you're trying to make people feel" vs. "the mechanics you're building" — good design starts with the experience/property and lets that guide the mechanics. Good technical vision works the same way.

Key vocabulary:
• capability-based vision — describing what the system will be able to do rather than how it will be implemented
• technology-agnostic — a design or vision that does not prescribe specific technologies, allowing flexibility in implementation
• desired properties — the qualities and behaviours a system should exhibit (scalable, deployable, observable) described independently of implementation

The "north star" metaphor is deliberate — a north star provides direction without specifying the route. The technical north star guides navigation through complex decisions without dictating every turn.

Effective technical north star statements are memorable and discriminating — they help the team resolve debates, not just inspire them. "Build a platform where any engineer can safely deploy any change to production in 10 minutes" discriminates: it would lead the team to invest in deployment automation and testing over performance micro-optimisations. A weak north star ("be the best engineering team") discriminates nothing. Staff engineers craft north star statements that encode the organisation's specific context and constraints: what's the most important thing the current architecture cannot do? What would change the most if we achieved it? The answers define a north star that is specific to this team's situation.

Key vocabulary:
• technical north star — a vivid, stable description of the desired technical future state used to guide architectural decisions
• discriminating vision — a vision specific enough to help resolve debates and prioritise trade-offs (as opposed to vague aspirations)
• navigating ambiguity — using a shared vision to make consistent decisions in situations where the "right answer" is not obvious

The combination of inspiration and direction is what makes a technical vision document useful rather than forgettable — inspiration creates motivation; direction creates alignment.

Techniques for writing inspirationally: (1) Use concrete sensory details — "an engineer can run a single command and watch their service deploy to production in real time" is more inspiring than "deployment will be automated"; (2) Describe the experience — what will it feel like to be an engineer working in this future system? (3) Name the problem being solved — "today we spend 2 days preparing for every release; in 3 years, release will be so safe we do it 50 times per day." Techniques for writing directionally: (1) Use measurable targets where possible ("10 minutes", "any service", "zero scheduled maintenance windows"); (2) Name specific architectural properties (event-driven, stateless, independently deployable); (3) Explicitly identify what will NOT be true ("we will not have shared databases between services"). The combination of vivid description and specific properties creates a document that is both inspiring to read and useful to reference.

Key vocabulary:
• inspirational writing — concrete, vivid language that helps readers experience the desired future state rather than just understand it abstractly
• directional specificity — sufficient detail to discriminate between architectural options (measurable targets, named properties)
• future-state narrative — a prose description of what the system will be like to work with once the vision is achieved

Vision communication is not a one-time event — it is an ongoing practice of repeating, demonstrating, and reinforcing until the vision becomes part of how the team naturally thinks about technical decisions.

Research on organisational change suggests a message needs to be heard 7+ times before it becomes part of someone's working mental model. The staff engineer's communication job is therefore repetition through different channels and contexts. The most powerful channel is decision-making: when the team sees the staff engineer consistently citing the vision in architectural reviews, design discussions, and trade-off debates, the vision becomes the shared language. Engineers also communicate vision through their code and architecture choices — a staff engineer who consistently makes decisions that align with the vision teaches by example, not just words. The combination of written vision, repeated verbal reinforcement, and demonstrated decision-making creates the conditions for shared alignment.

Key vocabulary:
• vision communication — the ongoing practice of articulating, repeating, and demonstrating the technical vision across multiple channels
• shared mental model — a common understanding of the technical direction held by all team members, enabling independent aligned decisions
• leading by example — demonstrating the vision through one's own technical decisions rather than only through words

The staff engineer's role is not to blindly follow complex code but to ensure alignment with the overarching technical vision. While caution is warranted, a simplification can be justified if it aligns with that vision – in this case, prioritizing performance. Simply reverting without understanding is inappropriate.

The staff engineer needs to address the junior developer's concern constructively. Acknowledging the inherent complexity of microservices while framing them as part of a strategic solution is key. Simply dismissing the concern or advocating for the status quo isn't helpful.

The staff engineer needs to translate the high-level vision into actionable steps. Defining KPIs is crucial for tracking progress and ensuring that the effort actually delivers the desired outcome (reduced latency). Simply relying on logs or a vague goal isn't sufficient.

The staff engineer needs to move beyond a general statement and proactively identify specific technical challenges. Suggesting a discussion about infrastructure, testing, and potential bottlenecks demonstrates foresight and helps manage expectations – crucial for successful feature delivery.

A good PR description should quantify the impact of changes. Providing specific metrics (e.g., % reduction in database load, ms improvement in API response times) demonstrates the value and allows reviewers to assess the effectiveness of the change more clearly.