Two quotes from the article stand out. First, from the X screenshot: "something about the process of writing makes your ideas 10x better". Second from near the beginning: "The most important person to convince is the author."
Design documents are so essential that even after mumble years in the industry, I am amazed when people, including putative "Product Managers" push back on the idea. As Leslie Lamport noted, "Writing is nature's way of telling us how sloppy our thinking is."
7.5 Years at Amazon, and even for my side projects, I write PRFAQs and share them with my stakeholders to gather feedback. I'm a PMT at Amazon, but in my alternative life, I code on many projects, and develop infrastructure, architecture, etc, and enjoy writing as much of it as I can.
I would extend that to working at a place with a design culture. That is engineers prefer to work on projects that have been designed including a written plan before starting. And mistrust or avoid leaders that cannot plan in writing, and projects that have not been planned.
All of this, plus, writing the documentation before building the app. I remember a Dilbert cartoon making fun of this being about the time I started realizing Dilbert wasn’t as smart as I had thought.
If you can’t write the documentation before you’ve written the code, you don’t understand well enough what you’re building the code for.
It’s one thing to jump into code because it’s fun to write code. But writing code is not designing software, and vice versa.
Same goes for APIs. Writing docs for an API that doesn’t yet exist can help create a much more complete and coherent API.
This is why I’m often trying to help stakeholders understand that the vast majority of software development has very little to do with actually writing code.
Herein also lies a concern I have about AI assisted development. It can be a powerful aid to the design stages, and it can be a powerful aid to writing code, but I’m not sure it enables skipping the design aspects altogether and somehow coming up with a complete, coherent product.
As a design reviewer, I think all design authors should internalize this concept:
> But a good doc will lay out the problem and mental models in a way that the solution that took weeks of hard thought to invent will be clear to the reader by the time the doc presents it.
Perhaps my favorite quote is: "If I had more time, I would have written a shorter letter."
Design docs should make complex things simple. They should not be a dumping ground for all the intellectual hardships and false starts the engineer went through. It may still worth capturing this, but that should be in another doc, or at least an appendix. Keep the path forward simple and understandable.
Two questions I ask myself are "will I get bikeshedding around this?" and "is this worth bikeshedding about?" My goal is to make the most difficult ideas trivial to talk about for first time readers, while avoiding the problems I know don't matter but will get a lot of comments.
I love docs written like this, and writing culture generally. But I've also seen something like this backfire a bit.
I think this approach is particularly good for docs where the assumption is the audience wants to understand why you reached the conclusions you came to, and the doc is sort of a persuasive argument. I think this is a valuable doc (and how I like writing and reading), but it is not always the case.
I think often you do want to start with the conclusion, the "end" so to speak, to orient the reader. And also to address the reader who trusts your judgement, and just wants to get up to speed. I've seen a lot of cases where the audience might not be ready/want to follow along w/ a train of reasoning, they want to know the punchline. And once they do, then they might want to follow up.
> Think of a design document like a proof in mathematics. The goal of a proof is to convince the reader that the theorem is true. The goal of a design document is to convince the reader the design is optimal given the situation.
We don't need to veneer technical writing in faux rigour for it to be worthwhile. That's the silly stuff that belongs on LinkedIn.
This kind of psuedo-rigor feels good to nod along to, but it's nonsense.
'We're not writing code, we're programming', 'we're not just programming, we're doing software engineering', and now 'we're not doing software engineering we're doing rigorous proof based mathematics' all of a sudden.
IDK how you write 'Think of a design document like a proof in mathematics.' without feeling at least a little bit silly.
> The goal of a design document is to convince the reader the design is optimal given the situation.
A proposed design may be optimal, or it may not, but the purpose of a design document is not to prove that the proposed design is optimal by any definition.
In a software development setting you're virtually NEVER formally proving anything, nevermind optimality.
You're writing technical fiction based in reality, nothing more. It's not a 'proof' of anything.
You're convincing stakeholders that your proposal can be feasibly built, is viable to run in the ecosystem of the rest of your codebases and infrastructure, and satisfies whatever business requirements that led to someone asking you to create a new $thing the design doc is aiming to propose the technical solution for.
Nothing more IMHO.
If your doc isn't doing those things then it's not effective, if it's giving the illusion of trying to do more than those things then it's just theatre.
The rest of the article is standard good writing advice, but can we not put design docs and PRFAQs on an altar as anything more than technical business fiction to communicate ideas and proposals for scrutiny to stakeholders.
This is my problem with design documents. If your stakeholders already have enough trust that they ask you to go build it without writing a doc, then what value does writing a design doc have.
Many will answer that it helps them think. But why do we need a formal process to think? Thinking is a valuable skill that should be practiced all the time.
Oh, I interpreted design documents as general things - documentation included.
Plenty of things at my current job have formal mathematical proofs backing it and it's helpful when justification is explained like that.
Invariants in networking architecture i need to carefully manage etc.
Depending on the culture some of this stuff is also needed once you get into politics land and need to present your ideas because you know it's better, no? Ig at a large company with too many business oriented minded people this line of work would fall flat
I have both read and written several design docs containing informal correctness proofs of nontrivial concurrent/ distributed protocols, so not sure where your dismissive attitude comes from. Not everyone’s environment or experience is exactly like yours.
In my experience, organization/clarity is the biggest hurdle for SWEs trying to improve their doc writing. I like the author's spaghetti code analogy for the importance of idea organization within a doc -- I've struggled to convey the same concept before and I will use this in the future. In the past I've talked about 'ferrying' the reader through your thought process but this post explains the concept in a more familiar way.
I wrote a similar post last year[0] and it was interesting to see the similarities (concision, importance of practice) and differences with someone from a different company. I'm not sure I agree about 'short paragraphs' -- that may be a natural consequence of high information density writing but line breaks themselves aren't much help if the ideas aren't distilled. The 'Editing' section gets at that underlying idea more directly imo.
Taking a class in technical writing greatly improved my ability to summarize written documents. The course emphasized a “cut with a red pen” approach (write, cross out, rewrite), which focused on using as few words as possible to communicate concepts and ideas clearly. This method has multiple layers and becomes easier with practice. I also try to share this knowledge with the teams I work with, but it’s important to remember that it’s a skill that requires regular training.
Solid advice on clarity and editing. The only gap is what happens after the doc is approved? Without upkeep it decays into "design archaeology." A few years ago, Andrew Harmel-Law wrote about an interesting approach to scaling architecture conversationally, which includes lightweight Architecture Decision Records (ADRs) as one tool that could help here. ADRs live beside the code (adr/001-use-postgres.md) and capture context, decision, and status in a format short enough to, I think, revisit in every PR and easy to supersede when reality changes so the original rationale stays searchable months later.
This is the case with Session messenger. It's been so many design and architectural changes that there's no single place that is authoritative of how it operates and works.
Btw use Signal if you want secure messaging, full stop.
Then do Security, Privacy, Compliance, and the review committees of all affected orgs become blocking reviewers on any PR that touches an ADR? Are these PRs getting merged in less than 90 days?
>Amazon meetings start with the presenter passing out copies... of a prose document... The meeting starts with everyone sitting in silence, reading the document, and adding notes and questions in the margins with red pen.
I've never worked at Amazon, but I've heard this a lot, and it always strikes me as an odd practice. Odder still is that it apparently works and everyone I hear talk about it seems to love it.
You're squandering precious meeting time by having everyone sit and read a document together. They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings.
And doing it synchronously means everyone either sits idle until the slowest reader is ready or not everyone gets to finish in time. And "slowest reader" isn't even just about reading speed. Presumably, some people can understand the document more quickly because they have more context.
In design reviews at Google, it was obvious that the majority of attendees came unprepared and were reading the docs for the first time while their teammates were discussing the doc. I suspect that the reason was that Google just didn't have a strong docs culture, and leads/managers quietly tolerated people coming unprepared (and sometimes, they themselves were unprepared).
I've never seen it done in practice, but I don't think it would be hard to have the best of both worlds where people review docs ahead of the review meeting, but there are strong cultural norms around reading docs ahead of time so the meeting is just for discussion, not just for reading or pretending that you've read.
Step 1. Brain dump into a doc (consider using dictation to get more thoughts down faster)
Step 2. Have an LLM give it structure & progression. You are ordering your thoughts for readability, so you'll probably want to throw it away. You're still refining your thoughts at this stage.
Step 3. Take the LLM output as a starting point, or write an outline from scratch. Flesh it out into a first draft
Step 4. simplify: cut words, swap big words for small words, etc.
Step 5. Repeat step 4.
LLMs bridge the gap from word-vomit to structure. You should be willing to throw away what you get from the LLM.
At least 30% can always be cut. It's amazing how much can be trimmed without losing the intent.
The meeting starts with everyone sitting in silence, reading the document, and adding notes and questions in the margins with red pen. Watching people mark up the document you spent so much time polishing is a strong forcing function to become a better writer.
Hated this about Amazon; I need to be in a certain state of mind when reading technical prose which is hard to arouse on a whim. Happy to make and submit edits prior to meeting and then discuss. I also much prefer token passing when making modification of the document, rather than simultaneous people marking it up.
I should write a lot more, but the two paths I see are: B.O.O. and Good Strategy/Bad Strategy.
B.O.O.: Background, Objective, Overview. Basically, a history lesson for how you got here, an objective for what you want to fix/change, and an overview of how you'll implement that change.
Good Strategy/Bad Strategy: An amazing book, but the organization is similar to boo. Problem Diagnosis, Guidelines/Assumptions/Requirements, and Actions.
I find BOO is better for targeted design documents in a google-like culture where you should write up a design document for almost any architecture change. The Good Strategy/Bad Strategy method scales pretty amazingly up to almost anything, but you need to be a much more experienced author to get things to fit it.
> The goal of a design document is to convince the reader the design is optimal given the situation.
This is a nitpick, but I don't think the goal of a design is to be optimal so much as sufficient.
Software systems design, like any design, is about coping with constraints and tradeoffs. The design doc should clearly lay out these out and present an approach that meets the requirements and constraints with acceptable tradeoffs. Where multiple reasonable alternatives exist, they should be make explicit along with a justification for why one option was chosen over the others.
Will it be perfect? Probably not, unless it is an easy problem or you over-designed. And even if it's a good design, it can hit unforeseen issues during implementation. The goal of design is not to eliminate all possibility of such issues but to mitigate risks and communicate to the stakeholders what we're building and why we're building it that way.
"Optimal" in this context includes time, effort and cost. So the design isn't perfect irrespective of these things, but it is optimal in terms of balancing the effectiveness of the solution with the effort put in.
The structure I prefer for a technical design document is like a three-layer onion.The first layer is the problem statement, goals, non-goals, and requirements, both functional and non-functional. The next layer is the functional specification, which describes precisely how the system will work from an external perspective. The third and final layer is the technical specification, which describes the internals.
Each section should follow from the previous. The design doc should justify to the reader (and author) that the problem is understood, the requirements are necessary and sufficient, the functional spec meets the requirements, and the technical spec implements the functionality and non-functional requirements.
As a corollary, if one section has a fatal flaw, there is no need to read on. If the problem is misunderstood, then the functional spec is likely wrong. If the functional spec doesn't meet the requirements, then the implementation is moot.
The issue I see very frequently is technical design documents that provide only the final section—a simple description of the system that will be built. As a design reviewer, there is limited feedback I can provide on such a design. Sure, it's a system, but will it solve the problem? Does the team even agree on the problem to be solved?
To add a little more color, each section also has a branch of possibilities. Given a problem, there are many possible functional specs that could solve it. Given a functional spec, there are many possible implementations. The act of choosing from among these possibilities is designing and the design doc should lay out the choices made (and sometimes the choices not made) and why.
I usually work on infrastructure as code, and I usually swap out the third layer of the design for the first layer of the implementation. You need a fully-specced functional design and a high-level technical design, but I've found that in many cases the technical implementation details can change as the project is developed, and that means either the low-level technical design and the implementation go out of sync, or there a heavy bureaucratic process in place to prevent that -- but the natural solution is to have the low-level design and the high-level implementation to live in the same place.
That still requires the rest of your process, and perhaps even places more emphasis on those documents. The infrastructure implementation needs to follow from the high-level technical design which needs to follow from the functional specification. Because as you say, the implementation needs to be reviewed against a specification. What are you reviewing if the spec is incomplete?
I see the third section as more of a feasibility assessment and for people to comment on whether the technical design is sufficient and extensible or to look for alternatives. It's ok if the design diverges from the implementation but I'd still look for it in a design review so people can point out any flaws or security/scalability issues proactively.
I often come across tips/pointers/exhortations about how to write good design documents. I generally agree that it's an important step: not just for clarifying your own thinking, but also for communicating effectively with others.
However, these types of posts often lack are concrete examples of what a good design document actually looks like. I understand that many of these documents are proprietary and intended for internal use. Still, are there any examples of well-written design documents available publicly that learners can study to get a clearer idea of what one should look like?
52 comments
[ 4.1 ms ] story [ 59.8 ms ] threadDesign documents are so essential that even after mumble years in the industry, I am amazed when people, including putative "Product Managers" push back on the idea. As Leslie Lamport noted, "Writing is nature's way of telling us how sloppy our thinking is."
For those wanting to learn how to improve the quality of their technical writing, see Write Like an Amazonian: https://medium.com/@apappascs/write-like-an-amazonian-14-tip...
A example doc would of been really helpful, I'd love to compare the final structure of mine with others.
That said, work back from your customer!
I would extend that to working at a place with a design culture. That is engineers prefer to work on projects that have been designed including a written plan before starting. And mistrust or avoid leaders that cannot plan in writing, and projects that have not been planned.
If you can’t write the documentation before you’ve written the code, you don’t understand well enough what you’re building the code for.
It’s one thing to jump into code because it’s fun to write code. But writing code is not designing software, and vice versa.
Same goes for APIs. Writing docs for an API that doesn’t yet exist can help create a much more complete and coherent API.
This is why I’m often trying to help stakeholders understand that the vast majority of software development has very little to do with actually writing code.
Herein also lies a concern I have about AI assisted development. It can be a powerful aid to the design stages, and it can be a powerful aid to writing code, but I’m not sure it enables skipping the design aspects altogether and somehow coming up with a complete, coherent product.
> But a good doc will lay out the problem and mental models in a way that the solution that took weeks of hard thought to invent will be clear to the reader by the time the doc presents it.
Perhaps my favorite quote is: "If I had more time, I would have written a shorter letter."
Design docs should make complex things simple. They should not be a dumping ground for all the intellectual hardships and false starts the engineer went through. It may still worth capturing this, but that should be in another doc, or at least an appendix. Keep the path forward simple and understandable.
I think this approach is particularly good for docs where the assumption is the audience wants to understand why you reached the conclusions you came to, and the doc is sort of a persuasive argument. I think this is a valuable doc (and how I like writing and reading), but it is not always the case.
I think often you do want to start with the conclusion, the "end" so to speak, to orient the reader. And also to address the reader who trusts your judgement, and just wants to get up to speed. I've seen a lot of cases where the audience might not be ready/want to follow along w/ a train of reasoning, they want to know the punchline. And once they do, then they might want to follow up.
We don't need to veneer technical writing in faux rigour for it to be worthwhile. That's the silly stuff that belongs on LinkedIn.
This kind of psuedo-rigor feels good to nod along to, but it's nonsense.
'We're not writing code, we're programming', 'we're not just programming, we're doing software engineering', and now 'we're not doing software engineering we're doing rigorous proof based mathematics' all of a sudden.
IDK how you write 'Think of a design document like a proof in mathematics.' without feeling at least a little bit silly.
> The goal of a design document is to convince the reader the design is optimal given the situation.
A proposed design may be optimal, or it may not, but the purpose of a design document is not to prove that the proposed design is optimal by any definition.
In a software development setting you're virtually NEVER formally proving anything, nevermind optimality.
You're writing technical fiction based in reality, nothing more. It's not a 'proof' of anything.
You're convincing stakeholders that your proposal can be feasibly built, is viable to run in the ecosystem of the rest of your codebases and infrastructure, and satisfies whatever business requirements that led to someone asking you to create a new $thing the design doc is aiming to propose the technical solution for.
Nothing more IMHO.
If your doc isn't doing those things then it's not effective, if it's giving the illusion of trying to do more than those things then it's just theatre.
The rest of the article is standard good writing advice, but can we not put design docs and PRFAQs on an altar as anything more than technical business fiction to communicate ideas and proposals for scrutiny to stakeholders.
Many will answer that it helps them think. But why do we need a formal process to think? Thinking is a valuable skill that should be practiced all the time.
Plenty of things at my current job have formal mathematical proofs backing it and it's helpful when justification is explained like that.
Invariants in networking architecture i need to carefully manage etc.
Depending on the culture some of this stuff is also needed once you get into politics land and need to present your ideas because you know it's better, no? Ig at a large company with too many business oriented minded people this line of work would fall flat
I'm usually the only person that ever reads my docs, so I write docs for me.
I also often write design docs during, and sometimes after my projects.
I call it Forensic Design Documentation[0].
[0] https://littlegreenviper.com/miscellany/forensic-design-docu...
I wrote a similar post last year[0] and it was interesting to see the similarities (concision, importance of practice) and differences with someone from a different company. I'm not sure I agree about 'short paragraphs' -- that may be a natural consequence of high information density writing but line breaks themselves aren't much help if the ideas aren't distilled. The 'Editing' section gets at that underlying idea more directly imo.
[0]https://ryanmadden.net/things-i-learned-at-google-design-doc...
Here’s a link to Harmel-Laws’post if anyone's interested: https://martinfowler.com/articles/scaling-architecture-conve...
"That’s it. That’s the Advice Process in its entirety." (speak to everyone involved).
Presumably anyone with the term Managing as a prefix in their job title is expected to glaze over at roughly this point.
Then we get to the meat: "The four supporting Elements". So I try to find out about ADRs:
I follow the first link:
https://www.thoughtworks.com/radar/techniques/lightweight-ar...
and eventually end up with this beauty (big download button at the bottom of the page from above):
https://www.thoughtworks.com/content/dam/thoughtworks/docume...
Would you mind pointing us at an actual definition of ADRs, please?
Btw use Signal if you want secure messaging, full stop.
I've never worked at Amazon, but I've heard this a lot, and it always strikes me as an odd practice. Odder still is that it apparently works and everyone I hear talk about it seems to love it.
You're squandering precious meeting time by having everyone sit and read a document together. They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings.
And doing it synchronously means everyone either sits idle until the slowest reader is ready or not everyone gets to finish in time. And "slowest reader" isn't even just about reading speed. Presumably, some people can understand the document more quickly because they have more context.
In design reviews at Google, it was obvious that the majority of attendees came unprepared and were reading the docs for the first time while their teammates were discussing the doc. I suspect that the reason was that Google just didn't have a strong docs culture, and leads/managers quietly tolerated people coming unprepared (and sometimes, they themselves were unprepared).
I've never seen it done in practice, but I don't think it would be hard to have the best of both worlds where people review docs ahead of the review meeting, but there are strong cultural norms around reading docs ahead of time so the meeting is just for discussion, not just for reading or pretending that you've read.
Step 1. Brain dump into a doc (consider using dictation to get more thoughts down faster)
Step 2. Have an LLM give it structure & progression. You are ordering your thoughts for readability, so you'll probably want to throw it away. You're still refining your thoughts at this stage.
Step 3. Take the LLM output as a starting point, or write an outline from scratch. Flesh it out into a first draft
Step 4. simplify: cut words, swap big words for small words, etc.
Step 5. Repeat step 4.
LLMs bridge the gap from word-vomit to structure. You should be willing to throw away what you get from the LLM.
At least 30% can always be cut. It's amazing how much can be trimmed without losing the intent.
Hated this about Amazon; I need to be in a certain state of mind when reading technical prose which is hard to arouse on a whim. Happy to make and submit edits prior to meeting and then discuss. I also much prefer token passing when making modification of the document, rather than simultaneous people marking it up.
B.O.O.: Background, Objective, Overview. Basically, a history lesson for how you got here, an objective for what you want to fix/change, and an overview of how you'll implement that change.
Good Strategy/Bad Strategy: An amazing book, but the organization is similar to boo. Problem Diagnosis, Guidelines/Assumptions/Requirements, and Actions.
I find BOO is better for targeted design documents in a google-like culture where you should write up a design document for almost any architecture change. The Good Strategy/Bad Strategy method scales pretty amazingly up to almost anything, but you need to be a much more experienced author to get things to fit it.
This is a nitpick, but I don't think the goal of a design is to be optimal so much as sufficient.
Software systems design, like any design, is about coping with constraints and tradeoffs. The design doc should clearly lay out these out and present an approach that meets the requirements and constraints with acceptable tradeoffs. Where multiple reasonable alternatives exist, they should be make explicit along with a justification for why one option was chosen over the others.
Will it be perfect? Probably not, unless it is an easy problem or you over-designed. And even if it's a good design, it can hit unforeseen issues during implementation. The goal of design is not to eliminate all possibility of such issues but to mitigate risks and communicate to the stakeholders what we're building and why we're building it that way.
Each section should follow from the previous. The design doc should justify to the reader (and author) that the problem is understood, the requirements are necessary and sufficient, the functional spec meets the requirements, and the technical spec implements the functionality and non-functional requirements.
As a corollary, if one section has a fatal flaw, there is no need to read on. If the problem is misunderstood, then the functional spec is likely wrong. If the functional spec doesn't meet the requirements, then the implementation is moot.
The issue I see very frequently is technical design documents that provide only the final section—a simple description of the system that will be built. As a design reviewer, there is limited feedback I can provide on such a design. Sure, it's a system, but will it solve the problem? Does the team even agree on the problem to be solved?
That still requires the rest of your process, and perhaps even places more emphasis on those documents. The infrastructure implementation needs to follow from the high-level technical design which needs to follow from the functional specification. Because as you say, the implementation needs to be reviewed against a specification. What are you reviewing if the spec is incomplete?
I'm a few decades into my career and can't recall ever seeing any.
However, these types of posts often lack are concrete examples of what a good design document actually looks like. I understand that many of these documents are proprietary and intended for internal use. Still, are there any examples of well-written design documents available publicly that learners can study to get a clearer idea of what one should look like?