Writing a good design document
grantslatton.com
Writing a good design document
1–10 of 152 posts
Re: Writing a good design document
#2Two 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."
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...
Re: Writing a good design document
#3I 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.
Re: Writing a good design document
#47.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.
That said, work back from your customer!
Re: Writing a good design document
#5> 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.
Re: Writing a good design document
#67.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. That said, work back from your customer!
Hadn't seen it that way - PR/FAQ - Press Release / Frequently Asked Questions https://productstrategy.co/working-backwards-the-amazon-prfa...
Re: Writing a good design document
#7All 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.
Re: Writing a good design document
#8As 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.
Re: Writing a good design document
#9Two 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, "Wr…
> Replace adjectives with data
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.
Re: Writing a good design document
#10I 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.