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

31–40 of 152 posts

Re: Writing a good design document

#31

Post by cadamsdotcom »

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 draft

Step 4. simplify: cut words, swap big words for small words, etc.

Step 5. Repeat step 4.

LLMs bridge the gap from word-vomit to structure. You should be willing to throw away what you get from the LLM.

At least 30% can always be cut. It's amazing how much can be trimmed without losing the intent.

Re: Writing a good design document

#32

Post by dasil003 »

kingkongjaffa wrote: post #13
apwell23 wrote: post #9

Earlier quoted context omitted.

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

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 agree with the sentiment, but not the conclusion. Sure, numbers can be abused, just like anything else, but they provided specificity which you can then interrogate and call bullshit on. I won't necessarily fault someone for leaving off the numbers and just speaking qualitatively to the large scale system rewrite they did, but it's harder to evaluate whether such an effort was indeed warranted or was just a lateral move post-hoc rationalized by an engineer who didn't understand the original system and needed to rewrite it just to achieve that understanding. Again, if someone is satisfying the business with such efforts, more power to them. As a hiring manager, I don't want to get into a subjective evaluation of the relative engineering value of specific work at an external company that I have no first-hand context on, but I do want to know that candidates understand the highest level goals they are hired to contribute to. Metrics, however flawed, give a good entry point into such conversations.

Re: Writing a good design document

#33

Post by prpl »

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

you squander sooo much more time whenever people are not on the same page, or if people are worried you didn’t cover their corner case.

Re: Writing a good design document

#34

Post by prpl »

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…

Expand, condense, compress, expand, compress.

Then somebody comes along and asks about something specific, so you expand.

Finally they use an LLM to compress after their pet idea was satisfied.

It’s crazy really, we’re just on a never ending rollercoaster here.

Re: Writing a good design document

#35

Post by miggy »

xrd wrote: post #29

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

At my company, we went from using detailed RFCs to one-pagers, and eventually to writing no formal docs at all. Over time, RFCs turned into artifacts optimized for promotions rather than alignment or clarity. In many cases, people ended up spending more time crafting the perfect document than actually implementing the solution.

Re: Writing a good design document

#36

Post by c-linkage »

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

In my experience if it doesn't happen in a meeting it doesn't happen.

Re: Writing a good design document

#37

Post by Uehreka »

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 because they had a meeting before that, etc.

On paper you could punch a ton of holes in this: Why not reduce the number of meetings people have to attend? Doesn’t the reading reduce the amount of time available in the meeting to actually make decisions? But it would seem that in practice they found that the meetings people were attending did in fact have value, and that even with the reading time a lot of decisions got made.

So this may just be one of those things where you have to look at the results instead of worrying about what could theoretically be done differently. And it sounds like people really like the results and that the benefits of this approach outweigh the drawbacks, at least at Amazon.

Re: Writing a good design document

#38

Post by marc_abonce »

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.

Re: Writing a good design document

#39

Post by commandersaki »

The meeting starts with everyone sitting in silence, reading the document, and adding notes and questions in the margins with red pen. Watching people mark up the document you spent so much time polishing is a strong forcing function to become a better writer.

Hated this about Amazon; I need to be in a certain state of mind when reading technical prose which is hard to arouse on a whim. Happy to make and submit edits prior to meeting and then discuss. I also much prefer token passing when making modification of the document, rather than simultaneous people marking it up.

Re: Writing a good design document

#40

Post by atomicnumber3 »

MOARDONGZPLZ wrote: post #15
apwell23 wrote: post #9

Earlier quoted context omitted.

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

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 largest impacts at the company. What would you have me put on my resume? "Decreased EC2 spend by a whole bunch!"? "Reduced EC2 spend"?

I don't get where this hatred of numbers on resumes is coming from. Is much of it probably bullshit? Yeah, just like most resumes. But I expect you to sort through it the same way you do the rest of the resume. Ask them about it. I can tell you the whole story of mine. I'd expect others can do the same. And if they stammer and crack, now you know how exaggerated it was.

Post reply on HN