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

31–40 of 132 posts

Re: How to write an effective software design document

#31

Post by bartread »

1over137 wrote: post #19
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…

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.

Same goes for highly regulated financial environments. If you work in banking you generally can't just FTX-and-hope your prototype, which is very much what GP sounds like they're advocating.

For starters you're going to have traceability requirements that can only be satisfied if you have a product requirements document and then often a software design document. Now you might well choose to manage all of that in JIRA and Confluence (or whatever) rather than sitting down and writing an actual document intended to be laid out and printed on paper but the fact remains the documentation exists and, indeed, is a must to satisfy compliance and regulatory frameworks.

As always, the domain you're working in and the organisation you're working for make a huge difference but, as much as there are plenty of places where none of this stuff matters at all, there are also plenty of places where it's incredibly important and that isn't going to change anytime soon.

Re: How to write an effective software design document

#32

Post by mtlynch »

baalimago wrote: post #26

Isn't much of this made redundant by being part of an existing system? Also, this level of detail is a recipe for being outdated once the issues and compromises starts coming in

Thanks for reading!

> Isn't much of this made redundant by being part of an existing system?

I haven't found that to be true in my work. If you're only making a minor change to an existing system, then you may not need a design doc, but a significant change to an existing system has as much, if not more, complexity and ambiguity than greenfield development.

> Also, this level of detail is a recipe for being outdated once the issues, compromises and compromises starts coming in

I think this is what people typically get wrong about design docs.

I don't think design docs are a good medium for being the perpetual, living description of the system. I think design docs should capture the design at the time of implementation. You should modify the design docs while you implement the work called for in the design document, but once you're done with that work, you freeze the document and preserve it for posterity only.

The design doc is about a specific change to the system. If you need a doc to describe the high-level architecture of the system as it evolves, that should be a different doc.

Re: How to write an effective software design document

#33

Post by ambicapter »

luc_ wrote: post #30
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 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.

Can you explain in which way they are outdated?

Re: How to write an effective software design document

#34

Post by mtlynch »

luc_ wrote: post #30
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 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.

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

Can you share more about how you think AI invalidates these rationales?

Re: How to write an effective software design document

#35

Post by flohofwoe »

luc_ wrote: post #30
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 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.

IME when starting a project from scratch, detailed upfront architecture specs are pretty much required to keep LLMs from flailing around too much (unless of course you build another cookie cutter CRUD webpage, those can simply copy paste from the millions of examples on the internet).

In a way it's a return to waterfall, just with faster implementation phases.

Re: How to write an effective software design document

#36

Post by biofox »

luc_ wrote: post #30
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 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.

In the age of AI coding, code is cheap. Getting the requirements and high-level architecture nailed down is where the hard engineering challenges remain.

Enter... documentation.

Re: How to write an effective software design document

#37

Post by GeneralMayhem »

luc_ wrote: post #30
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 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. The second most important thing is to precisely define common vocabulary - what are the important concepts in the problem you're solving, and how should they relate to each other? All of that information serves to ground the day-to-day work in what's important. I find myself starting every Claude session with "read this doc and get familiar with the world, then we'll get to work on a part of it".

(The same is true when working with humans, especially but not limited to junior engineers who aren't used to managing a project longer than a week or two. AI coding agents just never grow out of that phase.)

Re: How to write an effective software design document

#38

Post by superxpro12 »

1over137 wrote: post #19
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…

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.

I reflected upon a consumer product I worked on the other day, in the power tools market, and the damn thing had 3 processors in it.

I mean... when i was golfing, the cart had a gps enabled, cloud connected display that showed the golfers positions in front of us. I had a smart phone and a smartwatch with meter-accurate positioning to take a shot.

Software is beyond everywhere at this point.

Re: How to write an effective software design document

#39

Post by Tsarp »

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. This with a simple cli to help parse this has made the docs experience much quicker and nicer.

You can also generate svgs, mermaids etc on the fly now when you are really stuck on something.

Re: How to write an effective software design document

#40

Post by blanched »

fmbb wrote: post #15
felixgallo wrote: post #11

Earlier quoted context omitted.

You have successfully optimized for fast, but you have not optimized for quality, extensibility, customer experience, or maintainability. Fast can be a great thing to optimize for, but there are many other situations where other optimizations are preferable.

> you have not optimized for quality, extensibility, customer experience, or maintainability A ”software design” document does not optimize for either of those.

Why not? “Customer experience” is arguable, but most design documents I’ve seen involve the others.
Post reply on HN