Live data from Hacker News

How to write an effective software design document

refactoringenglish.com

41–50 of 132 posts

Re: How to write an effective software design document

#41
post #3

Author here. Happy to take any feedback about this post. I learned to write design docs at Microsoft and Google, and I thought they both had good culture around docs that hasn't percolated out as well as other engineering practices at those orgs. I haven't seen a thorough explanation of how to write design docs, so this is my attempt to externalize what I've learned about writing them.

This is good guidance, but what do you have to say about convincing your team of developers to live it out?

I've found that developers usually like writing code and avoid contributing to documentation. For some, it's actually scary because (edit: for them,) high quality writing is harder than high quality coding, and it can be avoided quite a bit.

On the project side, it's rare for the implementation and verification stages to not consume all the budget and more, and delivery creeping past the original optimistic date. So there's no time or money to spend on documentation.

The combination is that even with your great advice in hand, it's hard to navigate to really solid and comprehensive design documentation underpinning the products.

Re: How to write an effective software design document

#42
post #28

I’m curious how you handle design docs when requirements change significantly during implementation. At some point, updates and corrections can start describing a somewhat different project from the one that originally went through review. Is there a rule of thumb for when it’s enough to update the existing document, and when the design has changed enough to justify a new design doc and another review?

Yeah, this is difficult.

My rule of thumb is to ask myself, "Is there a chance my reviewers would not have signed off had this been in the design doc they reviewed?" If the answer is yes, I send it out for a follow-up and explain why I had to change the design.

In my experience, the response from my reviewers is generally, "Yeah, that's fine." It's a combination of (1) the practical limitations that it's hard for them to get the whole design back into mental context to argue about it and (2) they trust that I'm taking the design seriously and have thought this through. I think occasionally, I've sent a post-approval change out and someone points out something

It's common to encounter a curveball nobody anticipated at design time, but if you just go rogue and unilaterally make design decisions, it degrades trust and undermines the review process, so I want my reviewers to know that I'm taking their feedback seriously.

Re: How to write an effective software design document

#43
post #10

I've never experienced a situation where a software design document meaningfully improved the overall process. At best, it helps to keep the business in sync at the expense of a much longer delivery timetable. Even high level software delivery contracts never seem to stay on rails for very long. It is often faster to just build the damn thing and see where it lands. Software is not like a nuclear power plant or offsh…

Software is in nuclear plants, cars, oil platforms, pacemakers, everywhere. If one is writing more ‘disposable’ stuff like flashlight apps for smartphones, then sure, as you say. Others are writing serious stuff, and design docs are invaluable.

at least where i work the onus of "who creates the design doc" ends up on the developer.. who also builds the thing.. and thats just like a 2.5x translation tax on the developer who's realistically putting it together to appease business heads who want to feel involved.

i can think of... zero times where a business-coded person even a technical PM (which is a role i do appreciate btw) has ever come up with an official design doc or specification that didnt suck. creating a good design doc is either going to require an architect/staff or senior engineer to sit down and just do it. the overworked architect or staff engineer inevitably gets dragged in if the developers hands are full, or they just beat the shit out of the developer and fill their calendar up with meetings and make them do it... then they beat the shit out of them again and make them build it.. then they beat the shit out of them repeatedly doing fast follows for months and say "no not like that"

i think everyone wants to take some pride in the org they work at and maybe they feel like they've got the formula for sucess, but i personally haven't seen it. there's always going to be an additional translation tax required of the developer(s) who is/are also building the damn thing at the end of it. cover it in poorly run agile/jira shenanigans and this just slows down the possibility of getting to a super stable state back soooo far.

i actually agree with the guy a couple posts up: do some loose design work, friggen dropkick/prototype and see where it lands and go from there. i like facepalm when i hear that our project guys were planning a project for a year and when it was finally time to move on it every specification they planned out missed all the details. this is totally so much worse now with AI writing everything everyone is putting together.

Re: How to write an effective software design document

#44

My problem recently is to have people read design docs I'm writing.

It certainly feels like this is an intrinsic friction point in a world where more and more of the actual code is written by AI. I know in my workflows, reading a design doc of any length is a big tradeoff of time that could be spent building. Which isn't a new problem to have, of course, but as the time from plan->code->review->deploy keeps racing downward, "reading design docs" feels like it's ripe for disruption as far as how much time and attention it takes.

Re: How to write an effective software design document

#45
I was initially turned on to the idea of using specs by Joel Spolsky [https://www.joelonsoftware.com/2000/10/02/painless-functiona...]

I think they're valuable, both because they get you to think through the actual functionality (and underlying implementation) of the software, and the make sure that you and the [person you're developing for] are roughly on the same page. Plus, every edge case or design issue you catch while writing the spec saves you a ton of time.

That said, I think a big weakness of specs is that it's just not possible to write a perfect spec that doesn't have any blind spots and covers all the edge cases and issues you'll run into when actually developing. This makes it more difficult to hold the customer accountable to the spec, since you (the designer and devs) can't really be accountable to the spec unless you want to deliver some overly literal, not-actually-helpful product.

Re: How to write an effective software design document

#46
post #39

Lot of this is outdated. Including stuff that made a lot of sense in the past like diataxis and the google guidance. I've started to build docs structured as a skill. Since every model/harness is trained to handle skills well today. The entire docs of a project or modeled as a skill. I also have additional frontmatter on the md files. Specifically 2 keys -> when should you read, when you should not read this doc. Thi…

Why is diataxis outdated; don't your engineers ever read the code? Don't you think it helps the agents too?

Re: How to write an effective software design document

#48
post #39

Lot of this is outdated. Including stuff that made a lot of sense in the past like diataxis and the google guidance. I've started to build docs structured as a skill. Since every model/harness is trained to handle skills well today. The entire docs of a project or modeled as a skill. I also have additional frontmatter on the md files. Specifically 2 keys -> when should you read, when you should not read this doc. Thi…

Why do you think diataxis and the google guidance is outdated now?

Re: How to write an effective software design document

#49
The real question is "How to keep a software design document up-to-date". I have never seen this done in an efficient way. The first version is ok and over time it deviates more and more from reality.

So far my best experience has been to feed the whole thing into AI and get an overview of the project. That together with a few quick bullet points about the overall purpose of the system is pretty workable.

Re: How to write an effective software design document

#50
post #10

I've never experienced a situation where a software design document meaningfully improved the overall process. At best, it helps to keep the business in sync at the expense of a much longer delivery timetable. Even high level software delivery contracts never seem to stay on rails for very long. It is often faster to just build the damn thing and see where it lands. Software is not like a nuclear power plant or offsh…

Have you never encountered code that you thought was designed fundamentally incorrectly, but was too entrenched to change? That's what design review is for.
Post reply on HN