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