Design Documents
Or, write what you know
First off, thank you, to you my readers and collaborators, I appreciate all the feedback on the last post. Our last post answered some of the existential questions. This post is intended to answer a logistical question, “how should we present our ideas?”. With any luck, it will be both too deep and too cursory a treatment.
“Write what you know”. As a software engineer, what I know, is technical design documents. So, without further ado, let’s talk, briefly, about technical design documents, what they are, how to think about them, how to evaluate them, and how we’ll use them here in this newsletter.
The terms technical design document (TDD), Software Design Description (SDD), and Request for Comments (RFC, I prefer to think of it as Request for Collaboration), are often used fairly interchangeably, although the specifics may vary by company and domain, to describe the writing you do as a software engineer when proposing to build or modify a software system. For the purposes of this space we’ll simply refer to these formats as “design documents” going forward.
Design documents are one of the primary ways software engineers communicate their ideas. An engineer thinks through the problem, proposes a solution, and holds a review of the design document to communicate the problem and solution to other engineers and stakeholders, and uses the subsequent discussion to refine and drive consensus around a solution. That’s about it.
Lots of tech companies use design documents. In some cases, notably Amazon, the entire business, not just engineering, primarily operates through a process of document writing and review. The infamous Amazon Six Pager.
How should we think about design documents?
There are many good ways to write and structure a design document. Here’s some examples: Tensorflow, HashiCorp, one of many Amazon.
State the Problem Before Describing the Solution
For me, writing every design document begins with reading and attempting to internalize the Leslie Lamport’s memo below.
https://lamport.azurewebsites.net/pubs/state-the-problem.pdf
I find the subtle shift to to stating the problem and presenting solution-independent correctness conditions to the problem before I jump to the solution, which I am already chomping at the bit to propose, to be invaluable in improving the quality of my output. As a reviewer, focusing on correctness conditions independent of the solution presented, improves evaluation of the solution presented and makes it easier to think outside of the solution presented and propose alternatives.
What should we do with design documents?
Treat design documents as ephemeral artifacts used to drive a process
This is perhaps controversial, but I truly believe that the value of a design document is not in the resulting design document at all, but in the surrounding process. We should treat design documents as ephemeral artifacts used to drive a process and then discard them.
The value of a design document comes from its inputs and outputs. The input is the thought and investigation that went into the document, the elucidation of problems, correctness conditions, and solutions. The output is the discussion, consensus-building, and alignment that results from the design document review. The output drive next steps such as creating a work plan or implementing the solution that will produce concrete artifacts. Again, the design document exists only to facilitate this process.
There is no more draining feeling as a design document author than to have your document vivisected in realtime by an audience who then agrees to go with a completely different solution than what you had proposed and lovingly fleshed out. But, nonetheless, this is a successful result, your document drove collaboration and consensus.
Furthermore, no matter what you write, the actual solution you implement whether that is code, a work plan, a business plan, or something else will inevitably differ from your design document. Treating the design document as a enduring artifact wastes the maintainer’s time and leads to the terrifying outcome of having two separate and inconsistent sources of truth. Therefore, treat design documents as a point-in-time representation of the problem, proposed solution, record of the discussion that was had, and perhaps a draft of action items or a work plan that pave the way to more permanent artifacts.
So our primary considerations with design documents are:
Focus on the problem, solution-independent correctness conditions, and solution.
Treat the design document as an ephemeral artifact used to drive a process.
What else should we look for in design documents?
In addition to the primary considerations around design documents, here are some other things that I’ve found helpful as a writer and reviewer.
Race to two-way door decisions
Two-way door decisions are those where a decision is reversible and low-risk. Often, cases where a small experiment or proof of concept (POC) can resolve a question fall into two-way door decisions. The point of racing to two-way door decisions is, first to avoid getting bogged down on something that is easily reversible and can better be evaluated after some experimentation or implementation. And second, that if something is a two-way door decision it is often faster to just make the decision than go through the design document process. Not every problem needs a design document.
An important corollary here is to not contort the shape or length of your design document to some pre-conceived length but let your subject matter guide that decision. Six pages though is generally the most that can be digested and discussed in a sixty to ninety minute meeting. Depending on the degree of animation in the ensuing discussion, much less can be covered in that time.
Present trade-offs, make decisions
These are two sides of the same coin. If there’s only one viable solution you don’t need to have a design document or drive consensus you should probably just go straight to a work plan or implementation (see two-way doors). Unnecessary design documents are a great way to sour everyone on the whole process. Also, avoid throwing up straw man arguments. Again, if there’s a clear, correct solution you don’t need the design document process.
On the flip side, some design documents present numerous solutions but make no effort to evaluate these options leaving the readers to cobble together their own recommendations. The author of the design document, as the subject matter expert, should be making recommendations and evaluating trade offs. Even, if the reviewers disagree with the recommendation and the evaluation there is still a framework for that evaluation. On a related note, any time the author can provide a framework for evaluating different options, this can make the process easier.
You ain’t gonna need it (YAGNI)
There could probably be an entirely separate post just on the wisdom of this phrase in the field of software engineering and project management. But, specifically regarding design documents, it’s worth calling out. Design documents are castles made of sand, we build them from our imagination unaware that the reality of review and implementation will reduce them to nothing.
And so castles made of sand
Fall in the sea eventually
Jimi Hendrix, Axis: Bold as Love
It can be a beguiling siren song but we generally want to avoid excess elaboration, silver bullets, excess complexity, and overengineering. The design document should seek only to provide only the information necessary to understand and solve the problem presented and enable shared decision-making and ownership
It’s tough to avoid but as an author and reader I’ve often found that the solution that drives consensus and ultimately gets implemented is one that pragmatically reduces the ambition of the original vision. This encourages a more iterative approach and helps cut down on the scope and bloat of each design document. If you can be wise enough to curtail the scope of your design document early you can simplify both the writing and review process.
Kill your darlings, kill your darlings, even when it breaks your egocentric little scribbler’s heart, kill your darlings. Stephen King (and others)
Look around corners
Okay. Saved the toughest one for last. Good, thoughtful reviewers read through a design document, think about what’s presented and evaluate. Great reviewers think hard about what’s not in the document. Things the author didn’t think of, external constraints that may not be captured in the document, business, psychological, or interpersonal issues that may affect the decision. I wish I knew how to consistently be able to do this, but it all starts with taking a step back and looking at the problem statement and correctness conditions in the broader, holistic context of your existing knowledge.
Phew. Okay, time to get down off my soapbox.
So what does this all mean for this newsletter?
For the purpose of this newsletter much of what will be presented in the future is design documents chunked to fit the weekly post format with the intention that these “design documents” can be used to drive consensus and engagement that can be used to develop actionable next steps.
Hopefully, through this post I’ve presented how I think about design documents and given some tools to help evaluate these design documents. This will inevitably come in handy when I inevitably stray from the path I have set and innovate new ways to err.
That said, with apologies to all other equally valid formats, this is roughly the template we’ll be using, until we determine a better one.
Objective (optional)
Background (optional)
Problem Statement (a brief informal statement of the problem)
Tenets (optional)
Scope (optional)
In scope
Out of scope
Correctness Conditions (the precise correctness conditions required o f a solution)
Solution (the solution)
Satisfaction of Correctness Conditions (a proof that the solution satisfies the requisite conditions)
Challenges / Alternatives
Problems identified with the solution
Alternative solutions
Action items / Work plan / Next steps
I look forward to seeing you in our next post. We’ll be starting in on our first design document. Post your thoughts on design documents in the comments.