[HN Gopher] Writing a good design document
___________________________________________________________________
Writing a good design document
Author : kiyanwang
Score : 77 points
Date : 2025-08-03 20:21 UTC (2 hours ago)
(HTM) web link (grantslatton.com)
(TXT) w3m dump (grantslatton.com)
| patrickmay wrote:
| 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."
|
| 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...
| apwell23 wrote:
| > 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.
| kingkongjaffa wrote:
| 99% of bullet points containing numbers in a resume are made
| up, hamfisted BS, the other 1% cannot be attributed to a
| single individual so putting them in a personal resume is
| silly.
| Lich wrote:
| I don't blame people for doing so. That's what they have
| been told by recruiters to do to increase their chance of
| their resume not being thrown into the trash or be
| invisible. If there is someone to blame for this, it's the
| recruiting industry.
| corytheboyd wrote:
| It's so dumb. There is no way to verify the numbers, and
| yet, this stupidity weaseled its way into the LinkedIn
| cinematic universe of corporate bullshit. The same point
| but without the "X by Y%" hits the same for me-- besides I
| know what questions to ask to judge if you are actually
| capable of moving the needle, which is all I care about as
| a conductor of interviews.
| MOARDONGZPLZ wrote:
| If I get one more resume from a "seasoned professional" who
| has "decreased X by N%" I am going to close hiring, quit
| tech, and go be a hermit.
|
| N.B. I received such a resume while typing this comment and
| am absconding to Outer Mongolia as I type
| matt-p wrote:
| 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.
| kator wrote:
| 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.
|
| That said, work back from your customer!
| 01HNNWZ0MV43FF wrote:
| Hadn't seen it that way - PR/FAQ - Press Release / Frequently
| Asked Questions https://productstrategy.co/working-backwards-
| the-amazon-prfa...
| kator wrote:
| I also added an Appendix "Technical Stack Considerations,"
| but I like the PR and the FAQ's to focus on the customer/end-
| user's needs. The technical details matter, but they serve
| the customer outcome, not the other way around.
|
| A recent project's tech appendix had headers like "Core
| Technology Philosophy", "Backend Architecture", "Frontend
| Architecture", "Service Architecture", "Infrastructure and
| Deployment", "Security Architecture", "Performance
| Requirements", "Configuration Management", "Backup & Disaster
| Recovery", "Development Workflow", "Network Architecture",
| "Resource Management", "Development Principles", and
| "Scalability Considerations".
|
| The beauty is that by the time you get to the technical
| appendix, you've already validated what you're building and
| why it matters. The technical choices then flow naturally
| from the customer requirements rather than driving them.
| alphazard wrote:
| > 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.
| jmbwell wrote:
| 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.
| apwell23 wrote:
| Dilbert was just a normal person with average intelligence. His
| intelligence was magnified by ppl around him.
| B-Con wrote:
| 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.
| norseboar wrote:
| 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.
| kingkongjaffa wrote:
| > 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.
| klinquist wrote:
| Perfect for dragging into my context window :). Thanks!
| ChrisMarshallNY wrote:
| That note in the tweets above, spoke to me.
|
| 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...
| ryanmadden wrote:
| 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.
|
| [0]https://ryanmadden.net/things-i-learned-at-google-design-
| doc...
___________________________________________________________________
(page generated 2025-08-03 23:00 UTC)