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

51–60 of 152 posts

Re: Writing a good design document

#51

Post by zeroCalories »

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

Why does it matter when they read it? If they need more time for the meeting they can schedule more time. Only downside is that finding meeting slots becomes more difficult, but the total time spent doesn't change.

Re: Writing a good design document

#52

Post by zeroCalories »

B-Con wrote: post #8

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

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.

Re: Writing a good design document

#53

Post by [deleted] »

mtlynch wrote: post #42
Uehreka wrote: post #37

Earlier quoted context omitted.

> They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings. Amazon’s practice is a reaction to the fact that nobody actually does this. According to the article I read about this years ago, they realized that “creating a strong culture around reading before the meeting” also isn’t possible because many attendees had a meeting before this one, and couldn’t prepare for that meeting…

> Amazon’s practice is a reaction to the fact that nobody actually does this. But isn't that bizarre? I can't think of anything else where we need engineers to do something by a deadline, and we just resign to the fact that they won't do it unless we sit them in a room and babysit them while they do it.

[deleted]

Re: Writing a good design document

#54

Post by closeparen »

mtlynch wrote: post #42
Uehreka wrote: post #37

Earlier quoted context omitted.

> They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings. Amazon’s practice is a reaction to the fact that nobody actually does this. According to the article I read about this years ago, they realized that “creating a strong culture around reading before the meeting” also isn’t possible because many attendees had a meeting before this one, and couldn’t prepare for that meeting…

> Amazon’s practice is a reaction to the fact that nobody actually does this. But isn't that bizarre? I can't think of anything else where we need engineers to do something by a deadline, and we just resign to the fact that they won't do it unless we sit them in a room and babysit them while they do it.

The rule is not so much for the benefit of the kind of junior IC engineer who has time in his schedule to work on code, but for busy leaders whose experience of the world is otherwise 100% verbal.

Re: Writing a good design document

#55

Post by closeparen »

farkin88 wrote: post #23

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…

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?

Re: Writing a good design document

#56

Post by breischl »

cadamsdotcom wrote: post #31

One process that can work: 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…

I feel like the process of editing my own stuff is at least as important as getting it down. That's when I go back through it and realize all the conclusions I leapt to, things I didn't thoroughly consider, and other flaws. I think people really undervalue writing as a focus tool. But maybe that's just me, YMMV.

I think the same thing about a lot of code, too. Sometimes you really are just hammering out boilerplate. But a lot of times even writing test code is a great opportunity to realize the main code could be improved. But the LLM probably won't tell you that.

Re: Writing a good design document

#57

Post by breischl »

norseboar wrote: post #10

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

Nothing wrong with sticking a summary up top, and then laying out the arguments below.

Re: Writing a good design document

#58

Post by codemac »

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.

Re: Writing a good design document

#59

Post by rixed »

nlawalker wrote: post #46
mtlynch wrote: post #42

Earlier quoted context omitted.

> Amazon’s practice is a reaction to the fact that nobody actually does this. But isn't that bizarre? I can't think of anything else where we need engineers to do something by a deadline, and we just resign to the fact that they won't do it unless we sit them in a room and babysit them while they do it.

> I can't think of anything else where we need engineers to do something by a deadline, and we just resign to the fact that they won't do it unless we sit them in a room and babysit them while they do it Pretty much anything, unless you're in the engineer's management chain, or you've given them a direct incentive. It's always been my experience in bigco that people can ignore almost anything that doesn't come from t…

Then you should schedule two meetings: one in a reading room, at any time that fits each individual calendar, and then later the real one in a meeting room with everyone's involved, at the same time.

Re: Writing a good design document

#60

Post by rixed »

zeroCalories wrote: post #51
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'…

Why does it matter when they read it? If they need more time for the meeting they can schedule more time. Only downside is that finding meeting slots becomes more difficult, but the total time spent doesn't change.

In addition to the reasons already listed (slowest reader etc) it's also good, at leasdt for some, to let new information sink in before discussing it.
Post reply on HN