Writing Guides to Support Your Teams

When supporting teams in the many software engineering disciplines, we often help them define approaches to handling specific challenges. Writing them down on documents is an effective way to scale this process.

In his book An Elegant Puzzle, Will Larson (CTO at Carta) defines such documents as strategies, and he shares a lightweight structure that helps us define clear strategies for our teams.

In his own words,

Strategies are grounded documents which explain the trade-offs and actions that will be taken to address a specific challenge.

Although very familiar with writing guides for my teams (I prefer this word to refer to such documents), I found this simple process very helpful in communicating the message, and I started applying it in some documents I share with my teams.

Characteristics of a strategy:

• Its purpose is to share an approach to a specific challenge;
• It is practical;
• It is accurate and detailed;

You may write as many as you want. For a development squad, in my perspective, some guides we could define include:

• Effective Backlog refinement;
• Measuring our development process;
• How to write User Stories;
• Our on-call process;
• How to partner with other teams;
• etc.

According to the author, a good strategy consists of:

1. Diagnosis: The theory describing the challenge at hand, including its factors and constraints, alongwith a problem statement;
2. Guiding Policies: These are the policies that will be applied to address the challenge. They describe the general approach taken to tackle the problem;
3. Actions: These are the specific steps implemented to address the challenge.

This process is quite similar to how a doctor treats a patient. First, he names the disease or pathology (diagnosis of the problem); Second, he considers the therapeutic approach for it (guiding policy); Finally, he prescribes therapy or medication (actions to be taken).