Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Writing a good design document

grantslatton.com

Post reply on HN
Print view View original

121–130 of 152 posts

Re: Writing a good design document

#121

Post by mtlynch »

newAccount2025 wrote: post #120
mtlynch wrote: post #110

Earlier quoted context omitted.

I disagree. I think companies that have meetings like this have an immature meeting culture. Meetings are for low-latency collaboration, not information transfer. For example, reading a design doc is obviously more efficient asynchronously because everyone has different reading speeds and doesn't need everyone else in the room while they read. Arguing about tradeoffs in a design doc is usually more efficient in a mee…

> Meetings are for low-latency collaboration, not information transfer. Ok, but without a doc, collaboration in a meeting can become inefficient in many ways. Folks can talk past each other, bouncing between unclear options and losing clarity on what they are even debating. Only one person can talk at a time, so folks are sitting and waiting for their turn, etc.; Strong personalities can dominate and filibuster. Writ…

I'm arguing for reading the doc ahead of time, identifying topics about the doc to discuss, then coming to the meeting with a specific agenda.

>Ok, but without a doc, collaboration in a meeting can become inefficient in many ways. Folks can talk past each other, bouncing between unclear options and losing clarity on what they are even debating. Only one person can talk at a time, so folks are sitting and waiting for their turn, etc.; Strong personalities can dominate and filibuster.

I don't understand. These are just problems with meetings in general no matter what you do in advance. What are you arguing for?

>While reading the doc, everyone can comment in parallel, so you aren’t serializing the conversation for small things or letting some verbose person waste the time.

>Reading during the meeting helps folks manage time outside the meeting. It means: you don’t have to prepare for meeting you don’t own. It avoids “random people” assigning you work beyond what they are asking you for in your calendar. For busy managers this is a huge benefit.

I don't understand how this can be possible. It means that letting someone else manage your time is more efficient than managing your own time.

If I need 5 minutes to read a document, how is it helpful for someone to force me to sit for 10 minutes to read it at a specific time? It's obviously more efficient for me to read it in the block that I choose and not waste the extra 5 minutes.

The Amazon way sounds like how you'd manage time for a child, where you can't trust them to manage their time, so you have to schedule time blocks for coloring, recess, and eating lunch.

Re: Writing a good design document

#122

Post by sigbottle »

kingkongjaffa wrote: post #12

> 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…

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

Re: Writing a good design document

#123

Post by kingkongjaffa »

fsociety wrote: post #106
kingkongjaffa wrote: post #12

> 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…

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.

Writing for yourself is a good way to think.

Writing is also s good way to document to others that you have thought about the topic/problem/solution.

Re: Writing a good design document

#124

Post by Sinthrill »

cfiggers wrote: post #103
atomicnumber3 wrote: post #40

Earlier quoted context omitted.

What do you want to see, then? Colorful prose? I and a few others really did save my company 10 million dollars one year. It was in EC2 spend for a hadoop cluster. I can tell you how we did it and who did what. Yes it was actual dollars we would have otherwise paid to AWS, it is not funny money calculated by looking at sticker rates and ignoring our discounts (which were large). I'm proud of this and it was one of my…

I've only been a hiring manager once, and it was for a junior-level position so take that into account. When I read resumes, accomplishments meant next to nothing to me. I was looking for capabilities. Your EC2 example is probably an exception to what I'm about to say because EC2 is very well known and you can quantify the difference you made in real dollars. But, 99% of the time I have no frame of reference and ther…

> and you were well known to be a slacker? > what classes of problem

If people are going to lie on their resume there isn't a whole lot of anything you can do to fix that at the resume evaluation level. So many resumes have 100x skills where they say they know some language because they happen to walk by a room where someone might have been looking at the wikipedia page describing someone who might have used the language once accidentally.

If you can't relate the impact / accomplishment of the candidate for your job to your company,then that just speaks to a low quality resume. It should be obvious to any reviewer why what you did is relevant to their interest.

The reason why impact matters is that in some sense it should be theoretically reproducible. "Saved 100s of engineering hours by fixing some nonsense" which if true should speak to someone who can ostensibly save time while also understand the meaning of their work.

Re: Writing a good design document

#125

Post by dboreham »

jsty wrote: post #83
chartered_stack wrote: post #70

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…

The AWS Lambda PR/FAQ was released late last year - worth a read https://www.allthingsdistributed.com/2024/11/aws-lambda-turn...

Also not a design document?

Re: Writing a good design document

#126

Post by dboreham »

publicola1990 wrote: post #85
chartered_stack wrote: post #70

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…

Yes this is also a question that comes to my mind. Where are the design docs from the past 50 years of software development. There must be something concrete for people to study and learn from.

I've been doing this stuff for 40 years and spent the first 20 or so looking for design documents (having been asked to write many). Eventually I realized there are none. At least almost none, and very few that existed prior to the related software being written.

Re: Writing a good design document

#127

Post by barrystaes »

nickm12 wrote: post #64

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…

This +

Layer one also explicitly identifies stakeholders, and describes the current (AS-IS) situation with annonated screenshots so everyone quickly sees what we are talking about.

Layer two also lists alternative solutions considered and why not chosen.

Layer three is developers making a few notes on chosen tech design, most important is the choice reasoning here.

In all layers, add and use references. Less is more, a picture beats a wall of text.

Re: Writing a good design document

#128

Post by stronglikedan »

mtlynch wrote: post #30

> 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'…

> They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings.

There's no difference in the amount of time spent whether it's read in or out of the meeting. At least spending the time in the meeting to read it, people are more focused on the topic at hand and the time will be better spent. Besides, I'd bet the fraction of those docs that are ready sufficiently ahead of the meeting are in the single digits.

Re: Writing a good design document

#129

Post by senderista »

kingkongjaffa wrote: post #12

> 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…

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.

Re: Writing a good design document

#130

Post by nrvn »

I used the following sources to create an RFC template (and promote the document culture across the engineering documentation):

- https://www.industrialempathy.com/posts/design-docs-at-googl...

- https://github.com/rust-lang/rfcs

- https://github.com/kubernetes/enhancements/blob/master/keps/...

- https://blog.pragmaticengineer.com/rfcs-and-design-docs/

Hint: tailor the process and template structure based on your org size/maturity and needs. Don’t try to blindly mimic/imitate.

Post reply on HN