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.
patrickmay · 39m ago
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."
I think this idea got so pervasive all throughout tech that all the resumes that i now get are filled with so many numbers that i don't even know what to make of them.
B-Con · 4m ago
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.
matt-p · 36m ago
I sometimes even write design docs that will probably only ever really be read by me. It's so powerful to write these things down.
A example doc would of been really helpful, I'd love to compare the final structure of mine with others.
alphazard · 30m ago
> work at a place with a writing culture
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.
kator · 34m ago
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.
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.
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.
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."
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...
I think this idea got so pervasive all throughout tech that all the resumes that i now get are filled with so many numbers that i don't even know what to make of them.
> 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.
A example doc would of been really helpful, I'd love to compare the final structure of mine with others.
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.
That said, work back from your customer!
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.