Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How to write an effective software design document

refactoringenglish.com

Post reply on HN
Print view View original

81–90 of 132 posts

Re: How to write an effective software design document

#81

Post by barrkel »

AnimalMuppet wrote: post #75
barrkel wrote: post #67

Earlier quoted context omitted.

Instead of thinking through all the places in the code the AI is going to have to touch, why not kick off three parallel agents implementing the thing and finding out what they did and the tradeoffs they found? Planning is essential but it doesn't survive contact with reality. However, AI makes contact with reality cheap! Why not use it to improve designs, by writing the design after a few implementations have alread…

I'm looking for the places that need to be touched, but that wouldn't occur to me (and maybe not to an AI either) while I'm knee-deep in the code. Seeing where the AI touched isn't going to solve that.

If the feature works, and passes AI auditor agents with various hats (thinking of auth and security in particular), did that code you're not thinking of need to be touched? What effect did it have that cannot be captured in side effects, tests or audits?

Re: How to write an effective software design document

#82

Post by mckn1ght »

1over137 wrote: post #25
gbrindisi wrote: post #8

Claude, write a skill to create design docs as per this blog post /s In all seriousness a big chunk of my work is reviewing docs and 100% of the design docs I read these days are generated and there is a lot of slop. I have to parse them with AI to make sense of them, contributing to the problem. I wish people would follow a sensible set of rules like this one. Did anyone have any solution to this dread? Or cracked t…

>Did anyone have any solution to this Yes. Don’t “write” your design docs with AI. If you can’t personally enforce that, get your manager to.

I’d say don’t bother trying to parse it alone. Have a meeting where the person that created it presents it, and drill into anything weird.

If you can back them into a corner and force them to admit they don’t even understand something they supposedly wrote, use that as an opportunity to remind people it’s not acceptable to generate design documents that you don’t understand and then push them off onto other people.

Re: How to write an effective software design document

#83

Post by ffsm8 »

PaulStatezny wrote: post #68
mtlynch wrote: post #27

Earlier quoted context omitted.

OP here! I'll admit a lot of bias because I think design docs are extremely useful, but I find that when people hate design docs, it's almost always for one of two reasons: 1. The developer has worked on teams where design docs are viewed as a pointless ritual, so authors treat them as a pointless requirement and write bad docs and their teammates view them as pointless so they don't bother giving useful feedback, re…

I think your framing is fair here. But I'd like to offer an even more complicated/nuanced take: Designing in a group can be very difficult, and doing it well is a skill set that most people don't naturally have. I think this explains your point 1. Why do people view designed docs as pointless? Because they really don't have a vision or model for what and effective and healthy collaborative design process would look l…

> Designing in a group can be very difficult, and doing it well is a skill set that most people don't naturally have

Not only is it a skill every participant needs to have, they also all need to have a similar amount of competence and knowledge about the domain as well as the current implementation, otherwise it's mostly pointless ime.

But if all ven diagram circles overlap ... It is nice. I can count the times this materialized (in my professional life) on one hand. So I'm generally more towards the "make a prototype, then explain it to the others. Either it's the baseline for the discussion or the illuminating event that clears up wherever this approach works with that team.

Re: How to write an effective software design document

#84

Post by mtlynch »

CurleighBraces wrote: post #74
mtlynch wrote: 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.

So I tried this and it failed miserably. The documentation became the bible, and although I tried to keep the design goals at the conceptual/logical level the following would happen the moment the implementation started: 1. This is ambigous the docs need updating, please refactor your design 2. This doesn't work as the doc stated why did you get this wrong 3. The requirements have changed you need to update it The bu…

Thanks for reading!

What you're describing sounds like toxic team dynamics rather than something specific to design docs. Do you work effectively with your teammates outside of design docs, or is there similar tension/hostility everywhere?

What you're describing sounds like the design process working as intended (modulo the finger-pointing). The design doc should be unambiguous, and the implementation should match it.

Assuming this isn't just symptoms of a sick team, my other explanation is that your teammates find your deviations from the design doc unexpected. It sounds like you're running into situations where you can't implement the design doc as written, so you're proactively making your own design choices and showing your teammates the implementation. Could you loop your teammates in earlier on before you've implemented the code? Like, "The design docs says we're supposed to use SQLite, but I realized that SQLite doesn't support types the way we expected, so I think we should switch to Postgres for X, Y, and Z reasons."

Re: How to write an effective software design document

#85

Post by jiggunjer »

acrophiliac wrote: post #22

Some of the items in your document seem more like non-functional requirements that I would expect to find in a specification, not a design document,e.g., security, privacy, legal.

If they constrain design they're relevant. Doesn't mean every legal detail should be in the doc.

Re: How to write an effective software design document

#86

Post by sigbottle »

bob1029 wrote: 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…

It's mixed for me because there are certain things that I clearly think are needed. For example I'm building a custom network architecture and it's to the point where I'm using frontier models to reverse engineer game clients (while battling against the cyber safety system) for the sole purpose of validating that the network architecture I'm making is, if not "useful" (cause there's the game itself), at least different and superior. And to me the designs out there clearly are evidence of things not designed well and thought through ahead of time and instead a patchwork of hacks.

But then there are aspects I'm missing because while I've thought about the network protocol deeply, I'm not, say, a game developer who's ever gone through the whole game dev lifecycle. There's common patterns with software dev but it ain't it. There are probably so many things I have not thought about w.r.t. the whole deployment process that I'm not sure if letting AI vibe design+code it out is good or if I need to sit down and deeply work out the things I don't even know I don't know.

It's always a set of tradeoffs between things.

Re: How to write an effective software design document

#87

Post by cowthulhu »

mtlynch wrote: post #76
cowthulhu wrote: post #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 ca…

Fun piece of trivia, Joel published one of his functional specs.[0] As a huge fan of Joel's writing and engineering ideas, I was actually underwhelmed by his spec. It wasn't bad but it also felt like he missed a lot of opportunities to articulate design decisions to the reader more quickly or clearly. One obvious mistake is that there's over a page (in a 20-page spec) just dedicated to coding conventions and what pre…

I definitely agree that it's not perfect. I think he's a great starting point though, because when trying to get engineers to document stuff (something typically approached with similar enthusiasm to having their teeth removed with a hammer) it really helps if the "how to write a spec" doc is somewhat fun to read.

Unrelated - I really dig your "my [x]th year as a bootstraped founder" series.

Re: How to write an effective software design document

#88

Post by luc_ »

GeneralMayhem wrote: post #37
luc_ wrote: post #30

Earlier quoted context omitted.

I think in the age of AI coding, these rationales are a bit outdated. And if you think they're not - I'm curious to know why you think so.

Not OP, but I think they're way more essential with AI doing a lot of the coding. The biggest thing that AI, even the frontier models, is not great at is staying on topic and actually finishing a project with reasonable priorities instead of ratholing on insignificant details or claiming it's "finished" when it's half done. The most important thing that a good design doc does is specify what's in and out of scope. Th…

For an entire project? Yes I agree. For a feature or a submodule? I think when you work with claude to develop a plan, it's generally pretty good.

I guess my question stems from being rigid how a design doc should be defined, argued over, and then executed by humans. I think some of the details simply don't matter, and if they do, they often can be changed relatively quickly in order to adhere to the new requirement.

Try the claude-mem plugin.

Re: How to write an effective software design document

#89

Post by wpollock »

Two suggestions, based on my experience:

1) Add a section called "Potential Changes". This is broader than "missing features", and can include other items too, such as new hardware that might become avaliable, customer requirement changes you might anticipate, possible new technology (e.g. a new database or cloud service that might be useful), multilingual support, etc. Listing some of these often causes reviewers to think of others as well.

Ensuring the design is modular around such changes means implementing any of them will be far easier than if assumptions are hard-coded throughout the codebase.

2) Security and privacy are two aspects of a more general category of "compliance assurance". Those two are worthy of their own categories, but you should have a section covering any other legal, regulatory, or corporate requirements. The plan for auditing these compliances should be listed too.

Often, of course, there are none beyond security and privacy.

Re: How to write an effective software design document

#90

Post by luc_ »

murlax wrote: post #54
luc_ wrote: post #30

Earlier quoted context omitted.

I think in the age of AI coding, these rationales are a bit outdated. And if you think they're not - I'm curious to know why you think so.

We have debated this a lot in our organization. We are tired of seeing low effort Tech docs that puts the onus on the reader than the writer. I think that the writer should spend at least an order of magnitude of time more than the reader. If not, then the design doc can just be the LLM prompt that generated the document. I have actually resorted back to hand crafting TDDs and focusing on 1-2 page docs. It is a great…

Can you summarize your thoughts into a single prompt that, with the context of the codebase, gets expanded to something that makes sense?
Post reply on HN