Writing Architecture Documents (for developers)
Our colleague Martin was about to start working on a small-scale feature, an addition to a module that wasn’t open for extension and couldn’t easily support it.
He could shoehorn his use case on top of existing architecture without affecting others much or lay a more robust foundation over which he’d implement his use case. This could also help fix long-standing bugs and enable the implementation of new features that we foresee in our next two years (but would be hard to add now). In other words, “make the change easy, then make the easy change”.
We are a 20-people team organized into three pods (each with a Product Manager, a QA tester, and about three developers), designers, and leadership roles. The three pod structure helped us work without needing to have the context of the whole application in mind but made us need to sync up whenever a decision would affect others.
Martin postponed his solution in favor of determining a better architecture. He needed to write up a document to share ideas with everyone, ensuring we covered every pod’s needs and addressed the comparatively minor feature that led to these conversations.
Martin wanted the document to:
- be succinct, so everybody reads it, can share feedback, and signs off on –while also adding much detail to ensure no scenario (current or future) is left unattended
- use general language so his Product Manager can follow it while also using technical jargon, so his CTO will know precisely where we are heading
- be quick, so he can get going with his solution while also letting the document sit for days so people in different time zones share their feedback
How could he write the document with such competing goals? Martin and I paired on it many times, took notes, shared with the team, and wrote what worked well for us.
Definitions
First, Martin defined an objective, an audience, and a desirable trait for the document:
Objective: Efficiently communicate the problems and goals for the audience to discuss and support our decision, ideally without the need for meetings. Many people will read it many times, so we’ll take the time to make it clear and succinct.
Audience: For this case, our Director of Engineering. A single person, which in turn
helps define the level of detail, tone, and deadline for the document.
Interested developers and technically inclined Product Managers should be able to follow along a document intended for our Director
(or know whom to ask for clarifications).
Even if more people are deciders for the solution, it will help the writer to have
a single person in mind to whom he’s writing.
Desirable: Discuss at least two alternative solutions for the problem, outlining their pros and cons. What would the solution look like if we had all the time in the world? Or double our team size? Or only half of our team size? What if we needed to get something out in two weeks?
The document’s structure
Most developers at Epion have much less experience writing documents than writing code. Martin got a case of blank page block. How could he put in a couple of sheets of paper everything we discussed over lunch and on several calls, looking both at the short and long term? There were still open questions and even unknown unknowns!
I suggested starting from a template defining a structure. How should an Architecture Document look when skimming from afar? We wrote that down with some generic content that we’d iterate on for the feature and project at hand.
The blueprint with dummy content looked like this:
Bariloche (a short “catchy” name)
High-level overview
What we want (in order of priority):
- A great cost/benefit ratio (weigh up requirements and available resources)
- Seize a good risk/value ratio (some risk is acceptable for great value; what’s our aim and tolerance?)
- Make our teams happier (what specific teams, and what can we improve for them?)
Not a fourth! That’s enough; we shall define the top ones only. Also ok: “we don’t want to"s: we don’t want to continue seeing a current architecture problem.
Who will participate in this decision, who will approve it, and who are responsible for executing it.
When: a timeline and the "why” behind each deadline.
Top-down overview. We’ll achieve this by doing first some work that makes our pods and their stakeholders happy (the feature at the start of this story). We’ll also lay down foundations for our new architecture, enabling the fixes for long-standing bugs and paving the road for features on our horizon.
Alternative A
Description
Detailed description, supported with:
- ERD/class diagrams
- Database migrations (maybe a link, but nice to see them verbatim here to see not only entities but also their attributes and types)
- Implementation notes
- Use cases and sample data (could be a link to a GitHub spike PR, a linked document, or a block of code within).
It’s not a solution to apply as-is, but detailed enough that developers can “run it” in their minds and provide more specific feedback, saving time in future code reviews.
List of features enabled by the design and problems prevented by it.
Alternative B
Description
…
Comparison
Pros and Cons of considered alternatives.
Timeline
First Quarter: We’ll do the work that triggered this conversation. Pod and PM will be happy and timely get what they want.
Second Quarter: Developers will have a better architecture to more easily implement future work in our pipeline, such as A, B, and C.
Third Quarter: We’ll delete legacy implementations and run 100% on the design we want.
Conclusion
Described objectives will be met (expand this). We can’t identify additional risks (consider running “pre-mortems” to find more). We’ll be in a better place to implement future work without neglecting our short-term commitments.
Final thoughts
One goal is to avoid discussions until we have a mature draft with concrete alternatives. Discussions expand the space of possibilities (“design by committee”), while writing reduces it to its most essential components. Consensus means no ownership. But we do want to hear everyone’s feedback before making the decision.
In an Architecture Document we should use a tone different from what we are used to during code reviews: in code review we tend to ask rather than prescribe, use open-ended questions, and ask for early feedback. We’ll first avoid such early discussion, only describing a path forward. Discussions will come later.
With Architecture Documents we can implement our near-term work while aligning ourselves with the long-term vision for Epion Products.
I took some ideas in this article from:
- Square’s system to make decisions
- I first read about “Pre-Mortems” in “Thinking Fast and Slow” by Daniel-Kahneman (on our Epion Book Club)
- Julia Evans’ zine on writing for a single person