Your Slack is blinking for the hundredth time today, as multiple meetings chain together discussing the same topics over and over, with no decisions in sight.

This isn't just busy work - if teams can't reach decisions, it's because they're missing a broader direction. There's a deeper problem: the absence of a clear, shared technical vision.

While I strongly believe that "Product Leaders" in an organization must cultivate their ability to navigate ambiguity and embrace constant change, it's precisely their responsibility to bring clarity to this uncertainty - to provide direction and vision.

And there's one essential tool for this: writing.

The importance of the written communication

For years, I've been writing on eventuallycoding.com (and eventuallymaking.io in English), where I've publicly documented many key decisions:

• Our migration to Nuxt
• Should we measure the performance of an engineering team
• Feature flipping vs feature branching

While these are primarily technical topics, I've also written about broader subjects:

• Planning
• CTO from startup to scaleup

(This list is just for illustration - no need to read every article)

Of course, there are many other documents that remain internal to Malt, covering topics like internationalization strategies, payment platforms, and market approach.

These articles have helped to build up a heritage, a repository we can refer to understand the origins of various decisions, the trade-offs made in the past, and more broadly, the culture and mindset within Malt - as some articles extend beyond just the technical team.

These articles also allowed me to take a step back. When you write, you take time to document, source and educate yourself. Writing forces you to clarify, explain and synthesize.

In our context of a team distributed over several countries and several offices, it was also an advantage to encourage asynchronous discussion.

To put it plainly: the ability to write effectively is a hallmark of maturity - not just for technical teams, but for entire organizations.

This culture of writing can be found :

• at Amazon, which has developed a strong writing culture
• at Square, for example through Hype doc

But let's concentrate here on the use of this skill for a Senior+ (Staff, principal, etc...).

Writing a Vision

To create impact, you first need to know where you're aiming.

From Senior level upward, engineers must be able to write and articulate three types of documents: design documents, strategy papers, and vision statements.

On this topic, I must reference the excellent staffeng.com, particularly its chapter on engineering strategies.

I'll use their definitions for the types of documents we'll discuss.

Design Documents

Design documents are detailed descriptions of specific technical topics. Whether you call them ADRs, RFCs, or technical specifications doesn't matter much.

For example:

• Using OpenAPI as a contract between client and server
• Methods for securing REST calls

These are concrete documents that describe how we actually use a technology in our context.

Strategy Documents

Beyond design documents come strategy documents. While these can also take the form of RFCs, ADRs, or roadmaps, they serve a different purpose. Strategy documents take a higher-level view than design documents - they clarify our approach and provide guidance around technology choices.

For example, a strategy document might define:

• How we should use REST APIs for microservices communication
• Why we prefer message buses over REST for inter-service communication
• How and why we're planning to migrate away from MongoDB

Strategy documents often emerge from team debates and conflicting viewpoints. Their purpose is to:

• Highlight the trade-offs considered
• Document the final decision
• Explain the reasoning

Unlike design documents which describe how things are, strategy documents express an opinion about how things should be.

Vision Documents

Finally, let's discuss long-term vision. Here, the format shifts into broader documents such as:

• North Star documents
• Engineering Principles (or Pillars)
• Manifestos
• Technology Radars
• Engineering Blog Posts

And more - this list isn't exhaustive.

A vision document sets direction for several years into the future. Taking our previous examples further, it might address questions like:

• What will our inter-service communication patterns look like in three years?
• How will these communication patterns integrate with our next-generation monitoring system?
• How will we implement zero trust principles across our microservices architecture?
• What direction should our front-end architecture take over the next three years?

While these examples focus on technical aspects, vision documents can extend beyond pure technology. They might address product direction, AI adoption strategy, team organization, and many other interconnected topics.

How to Get Started?

Writing a vision document can be daunting when you've never done it before. It took me years to learn how to craft effective strategy and vision documents.

Today, I follow a consistent process that aligns with Will Larson's approach in his chapter on engineering strategy. It follows three main phases:

1. Document the past (through design documents)
2. Address the present (by capturing conflicts in strategy documents)
3. Envision the future

More specifically, here's how to approach it:

1. Begin by writing several design documents about your existing systems
2. Group these documents by theme, identify open questions and contradictions, and develop strategies
3. Group related strategies together and project their impact into the future

Remember: this isn't a solo endeavor, nor is it set in stone. It's both collaborative and iterative by nature. This approach is what makes it such a powerful storytelling tool - it evolves and improves through collective input and refinement.

Storytelling

This connects to a previous chapter on tech marketing and the importance of promotion and selling.

Being a senior in a product organization goes far beyond executing assigned tasks - I hope I've made this clear throughout. It's about identifying problems and proposing solutions.

However, no solution or vision ever implements itself. You must communicate and convince others.

This becomes even more critical as you aim for broader impact - the more people your changes affect, the more funding they require.

While the documents mentioned above are necessary, they alone aren't sufficient. But, when well-crafted, they help you build the narrative needed for both successful promotion and change management.

Through iteration, these documents evolve to address objections. Through collaboration, they help create "champions" who will help spread these ideas.

When built on solid foundations - observations, trade-offs, and lessons learned (from strategy documents), along with other elements like benchmarks and both qualitative and quantitative studies - they provide the basis for a narrative that resonates with everyone, technical and non-technical alike.

Let's break down how each document type contributes to your story:

Design documents serve as your "proof points":

• They provide concrete details and facts
• They demonstrate technical mastery
• They build a credible foundation for your arguments

Strategy documents tell the "how":

• They explain choices and their rationale
• They show the paths considered and chosen
• They build your narrative's logic

Vision documents address the "why":

• They provide direction and purpose
• They inspire and motivate
• They help others see themselves in the future state

Questions

• In the last 6 months, what documents have you written that are still consulted today by your colleagues?
• During your last major technical change, did you document your thinking beforehand? If so, how did this document evolve with feedback from the team? If not, what obstacles did you encounter that could have been anticipated in writing?
• Do you document the decisions you don't make? The compromises that led you to rule out certain options?
• In your organization, what is the process for sharing a technical vision? If you were to propose a major architectural change tomorrow, what would be your first written document?

Resources

• Writing an engineering strategy
• Tech Marketing
• Amazon's writing culture
• Hype docs at Square