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

41–50 of 152 posts

Re: Writing a good design document

#41

Post by commandersaki »

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…

This is the case with Session messenger. It's been so many design and architectural changes that there's no single place that is authoritative of how it operates and works.

Btw use Signal if you want secure messaging, full stop.

Re: Writing a good design document

#42

Post by mtlynch »

Uehreka wrote: post #37
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. 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.

Re: Writing a good design document

#43

Post by melagonster »

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.

They just do not allocate time to read documents for engineers.

Re: Writing a good design document

#44

Post by xrd »

marc_abonce wrote: post #38
xrd wrote: post #29

The opposite of this is a culture where "we just work it out in slack."

Actually, I often find that old Slack conversations can be the most helpful representation of how a program works in real life and how to troubleshoot it and workaround its shortcomings. The official documentation is often too concerned to be concise and "pure" (OP compares it with a mathematical proof) so it only represent an idealized version of a software that didn't ever exist.

I follow you.

I do like discussing things after the fact. I think a "proof" is a good starting point, and if you don't start with at least that, then jumping into a slack conversation to do that foundational work causes problems.

I really like a PR as as the place to put the proof: you can only assume it is true for that moment in code, and it is associated with that. Of course it isn't remotely true as all software has bugs, but at least it can be a concise statement of how you understood it at the time, and that's valuable. The author is noting that you need to get into the mental model of the author, and this is a good place to capture your thinking.

I think READMEs for a repository, in general, are almost always worthless and outdated, like you allude to.

Re: Writing a good design document

#45

Post by pertymcpert »

atomicnumber3 wrote: post #40
MOARDONGZPLZ wrote: post #15

Earlier quoted context omitted.

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

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…

You can complain all you want on here but it's not going to change the fact that most readers including myself just glaze over them. Because as you say most are just bullshit.

So keep doing it if you don't actually care. If you do, maybe try to think of a different way to communicate it that sets you apart.

Re: Writing a good design document

#46

Post by nlawalker »

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.

> 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 their management chain up until scheduled meetings get involved. Being uncooperative with meetings (declining invites without alternatives; not attending; not participating) are when escalations and complaints start occurring, and there seems to be a silent consensus that this is the standard - as in, if you complain that someone hasn't answered your emails, the standard response you should expect from anyone, including their manager, is "then schedule a meeting."

So, if you need someone to do something, you schedule a "meeting" to block time on their calendar in which they will pay attention to your thing. That includes anything they need to do to prepare, because anything you don't include in that time block isn't part of the meeting and therefore isn't going to get done.

Re: Writing a good design document

#47

Post by thunderfork »

pertymcpert wrote: post #45
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…

You can complain all you want on here but it's not going to change the fact that most readers including myself just glaze over them. Because as you say most are just bullshit. So keep doing it if you don't actually care. If you do, maybe try to think of a different way to communicate it that sets you apart.

[dead]

Re: Writing a good design document

#48

Post by wavemode »

dkdcio wrote: post #28
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…

I prefer "more time, shorter letter"

"T ∝ 1/L"

Re: Writing a good design document

#49

Post by SatvikBeri »

pertymcpert wrote: post #45
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…

You can complain all you want on here but it's not going to change the fact that most readers including myself just glaze over them. Because as you say most are just bullshit. So keep doing it if you don't actually care. If you do, maybe try to think of a different way to communicate it that sets you apart.

I generally like it when resumes do this, and so do most people I know. I'd be interested to see surveys, I don't think it's anywhere close to universal. That said, I'm typically focused on very measurable domains (e.g. making code faster.)

Re: Writing a good design document

#50

Post by kjellsbells »

Lich wrote: post #16
kingkongjaffa wrote: post #13

Earlier quoted context omitted.

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.

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.

Not you specifically, but as an industry response, that seems too pat.

The recruiters will do and react to what the hiring managers ask for. When one too many candidates slip thru who bullshit, or there is weak signal that such and such method of candidate selection seems to result in marginally stronger candidates, then everyone rushes to do that thing and it eventually becomes sludge. Leetcode interviews are a classic example.

We (individuals) get poor candidates because we (industry) encourage and reward poor recruitment practices. Time for us all to look in the mirror, honestly.

I've seen 300k salary hiring managers punching down on a recruiter making 60k who doesnt know her C# from her C++. That sort of behavior says more about the flaws of the hiring manager than the recruiter. If you never talk to the recruiter but once a year when you have budget to hire someone, never take the time to educate them on your business, well then you're going to get crappy candidates.

Post reply on HN