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

21–30 of 132 posts

Re: How to write an effective software design document

#21

Post by verdverm »

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…

> No one actually has to give you permission to do anything.

For now, in the current context (with ai), it seems like a non-ignorable portion of society now wants to limit what kind of code people can write, Ai is apparently sufficiently like nuclear science that regulation may come to the act of producing code.

Re: How to write an effective software design document

#23

Post by pif »

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…

The software development realm is bigger than web programming.

Re: How to write an effective software design document

#24

Post by 0xbadcafebee »

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…

Your second paragraph is the impetus behind Agile Software, and we've all seen how fantastically that failed. Lots of code pushed out quickly, but also a lot of really shitty products, uncertainty, never-complete projects, dysfunction between teams, etc.

> Software is not like a nuclear power plant or offshore oil platform

No, but it does impact people's lives significantly. How many times has your personal information been leaked by a company making products by people who didn't care? Who would have predicted that a security company's terrible QA would lead to 8.5 million crashed systems, 42,000 delayed flights, 10,000 cancelled flights, and over $10B in economic losses? I'm sure the developers just said "not our problem". But their lack of concern, and "just throw shit at production" mentality, had real world consequences.

Re: How to write an effective software design document

#25

Post by 1over137 »

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.

Re: How to write an effective software design document

#27

Post by mtlynch »

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…

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, reinforcing everyone's belief that they're a pointless ritual.

2. The developer does not like other people questioning their engineering choices, and they know that it's harder for their teammates to push back on finished code than a design doc. Investing in the implementation before design changes the calculus to bias in favor of whatever's already implemented rather than what would have been the ideal implementation. Plus, it's harder for the team to review design decisions of 10k LOC than a 5-page design doc.

Re: How to write an effective software design document

#28

Post by nseskin »

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?

Re: How to write an effective software design document

#29

Post by pydry »

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…

100%. I find it's generally used as a waterfall practice - i.e. BDUF first with a design document, then implement instead of "implement following conservative assumptions, revisit and refactor aggressively".

The latter being vastly more effective at honing good design because more decisions are made in retrospect.

I find that a spike or a spike PR to demonstrate a new approach (if a software design decision is controversial) is 10x as valuable.

Re: How to write an effective software design document

#30

Post by luc_ »

mtlynch wrote: post #27
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…

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 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.
Post reply on HN