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

111–120 of 152 posts

Re: Writing a good design document

#111

Post by closewith »

anal_reactor wrote: post #108
closewith wrote: post #91

Earlier quoted context omitted.

Without fail, people who say this really mean "I am unable or unwilling to put in the hard work at the design stage to resolve uncertainty and will instead push these problems downstream to the development process where hopefully no-one will remember I'm responsible for the ensuing mess".

Yes, that's correct. In other words, my cost-benefit analysis concluded that shipping fast and iterating later is a much better strategy than spending countless manhours on plans and meetings in order to provide a product that is perfect from technical perspective but misses both the timing and market needs. I don't understand this fetishation of "perfect code" when experience shows again and again that for most use…

> I don't understand this fetishation of "perfect code" when experience shows again and again that for most use cases, the correct approach is to ship fast and fix later.

You're conflating two separate issues, because design documents help you ship faster and fix later. They do this by making you think about what you're building, thereby allowing you and downstream consumers of the plan to focus on a smaller and more valuable set of goals.

Your approach is the opposite - building by gut feel and ignoring the available data. That's leads to wasted effort and elongated development cycles.

> my cost-benefit analysis

You don't plan, so you don't know your costs or benefits.

Re: Writing a good design document

#112

Post by apwell23 »

taude wrote: post #105
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…

That's a good example for a success. I've seen resumes from Junior devs with <2 years experience, where every line item was a business goal met, and almost nothing on their technical skills they've gotten. Been a hiring manager 10+ years, and it's a trend I've seen more recently.

that formula is preached non-stop on reddit /csmajors /cscareers ect .

Re: Writing a good design document

#113

Post by layer8 »

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

Presenting such numbers to motivate management is a frequent advice on the Soft Skills Engineering podcast [0]. I agree that their (the numbers’) meaningfulness is often doubtful.

[0] https://softskills.audio/

Re: Writing a good design document

#114

Post by chnsh »

Logistically speaking, is there a good hosting service for design docs but have google docs-like functionality to be able to comment and share feedback? I increasingly use tools like cursor to iterate on design docs that are in markdown format and currently I move things over to google docs manually and when there is feedback, I need to go back to cursor which creates a slow and weird loop. Have people identified better structures/processes for this?

Re: Writing a good design document

#116

Post by Esophagus4 »

Scarblac wrote: post #65

Is there a collection of good design documents somewhere? I'm a few decades into my career and can't recall ever seeing any.

I would also love to see some so I can share them with my team.

We’re a very tribal company so standards vary widely, and I’m curious to see what industry gold standard looks like.

Re: Writing a good design document

#117

Post by chromatin »

The author makes the following assertion:

    Let me illustrate a common code organization issue some programmers run into on their first day. The novice writes

    terminal.print("Hello world")

    Then they decide they want to make the text red, so they edit their program to

    
    terminal.print("Hello world")

    terminal.setPrintColor("red")
        
    And then they're confused that it didn't come out red. They haven't internalized that the first line of code happens before the second. They just get a soup of code on the screen that kind of has the ingredients for a program, and expect the computer to do what they want.
I find this _extremely_ surprising???

Re: Writing a good design document

#118

Post by dayjaby »

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…

> However, these types of posts often lack are concrete examples of what a good design document actually looks like

The entire post is an application of his document designing philosophy. It became obvious with his first header being "Goal" and him mentioning to set a goal early on.

Re: Writing a good design document

#119

Post by codazoda »

chnsh wrote: post #114

Logistically speaking, is there a good hosting service for design docs but have google docs-like functionality to be able to comment and share feedback? I increasingly use tools like cursor to iterate on design docs that are in markdown format and currently I move things over to google docs manually and when there is feedback, I need to go back to cursor which creates a slow and weird loop. Have people identified bet…

We use Notion and most people seem to like it. I find it quite quirky but it does a good job of allowing comments and feedback that can then be marked as "resolved".

I'd probably prefer a pure markdown solution but I'm not aware of one.

Re: Writing a good design document

#120

Post by newAccount2025 »

mtlynch wrote: post #110
joshuamorton wrote: post #89

Earlier quoted context omitted.

> 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. This is practically the point of meetings. Meetings exist as a forcing function to achieve communication that likely could have happened asynchronously but for some reason didn't.

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.

Writing even a bad doc ahead of time can help to make the meeting’s purpose clear. The author can guide the discussion by laying out and labeling big options and decision points.

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.

Post reply on HN