In my recent conversations with colleagues who have been recently promoted to staff engineer positions, I’ve observed a tendency to underestimate the value of high-level visionary documents in favour of highly detailed design documents for upcoming features. Many believe that “abstract conversations about the future” detract from actual work. However, I strongly believe that a certain portion of visionary docs brings a significant boost for the software team. And in this article, I will show how.

Definition

Let’s begin by clarifying what I mean by the term “vision doc”. A vision doc is a concise document that outlines high-level aspects of a project or initiative, looking ahead to a time frame of 1-3 years. The technical orientation of vision docs can vary, ranging from very technical ones like “We will migrate from a Framework A to a Framework B” to more product-like descriptions such as “We will deliver an exceptional user experience.” Usually the technical bias of the vision is expected from software engineering roles.

As a staff engineer, you possess knowledge of ongoing projects, team/org challenges, and business requirements, allowing you to identify opportunities, align work with business needs, and describe a target state for the future. This is an organisational context and a vision doc is a derivative of this context expressed through an inspiring picture of the future. So you finds some opportunities, aligns work to business needs and describes this as a target state for the future.

Advantages of Vision Docs:

  1. Initiating discussions: By verbalizing and recording a version of the future, a vision doc stimulates valuable discussions among team members. This process allows for the expression of disagreement and the identification of potential weaknesses, enabling the team to align and work towards a common goal.
  2. Supporting funding conversations: Vision docs serve as a foundation for conversations about funding with upper management. If you want your teams to grow, it is essential to demonstrate where the business’s investment will be directed. Highly detailed design documentation may not be suitable for this purpose due to its large size and overload with details that are redundant for folks at a strategic level.
  3. Motivating the team: Similar to the popular story about three bricklayers, individuals are more motivated when they have an inspiring aim to strive for. Also this document can reduce anxiety a little. People see the amount of work for a long time ahead and worry less about being fired due to absence of tasks for them.
  4. Coordinating efforts: Vision docs require a significant amount of contextual information. By sharing these documents, you can provide lower-level engineers with essential guidance, directing their efforts towards the most crucial areas.

Challanges:

  1. Balancing vision and execution: A vision doc alone cannot move your product forward without actual work. After aligning the vision, it is crucial to create detailed designs and write code. To avoid this pitfall, consider two strategies: set specific timeframes for writing vision docs as a preparatory activity, and limit the amount of time teammates spend solely on vision. Additionally, provide a more detailed description of the first step towards the vision, ensuring clarity and increasing the likelihood of successful execution.
  2. Addressing obsolescence: Visions can become outdated rapidly. To combat this, strike a balance between the level of abstraction, areas covered, and the time spent on the document. Avoid investing efforts in aspects that are likely to become obsolete in the near future.
  3. Embracing flexibility: A vision should not be rigidly fixed, as the world is constantly evolving. As we move towards the goal, we learn new information, so it is quite normal that we can correct the vision after some time. It is important to strike a balance between flexibility and progression, avoiding chaotic shifts in direction.

Conclusion

So the vision doc is a powerful tool that can align teams, represent teams on upper management meetings and even reduce anxiety. So a good engineer should be able to use this tool and apply it when necessary. I hope this article was able to show its importance and dispel doubts whether to write a vision document or to code a little.