I've found the design doc itself is relatively useless once it has been created, but that the act of creating the design doc is an indispensable part of the process. Spending time and getting your thoughts organized before diving into the team, the management and the editor makes a huge difference.
How to write an effective software design document
61–70 of 132 posts
Re: How to write an effective software design document
#62Lot 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…
Referencing Joel Spolsky's article about how you should never do a rewrite is starting to feel outdated as well.
Re: How to write an effective software design document
#63Earlier 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.
> 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?
The biggest thing AI enables is cheap code.
That means you could choose to try three (or more) genuine implementations and explore their tradeoffs, instead of making three proposals in a document with one recommended (and the other two usually only provided for contrast).
I do think the design is important to keep around - in particular, the constraints, the communication points, schema, tacit things that might not be clear in code. I am not certain that the design should precede the implementation for features below a certain size though.
Larger efforts need milestones and collaboration and will have multiple people doing implementation, so there's more need to agree schemas, APIs etc up front there.
Re: How to write an effective software design document
#64> A good design doc can save you years of development time
Brainstorm with your agent in a new session, ask a thousand questions, at the end ask for a detailed prompt.md to develop an app then tell it to comply
There, saved years of development time in AI era
Re: How to write an effective software design document
#65I think specs are incredibly valuable for who's writing/developing the software as a thought exercise, and pretty much useless for anyone else, especially after you ship it as it'll always get outdated very quickly.
Re: How to write an effective software design document
#66I'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 is often faster to just build the damn thing and see where it lands.
Part of documentation is figuring out if you're building the RIGHT thing. It give the opportunity to get feedback from more than one party.
The usability of most modern (complex) application is deplorable. I see things that a paper prototype with 5 people on the street should have stop dead in its tracks being rolled out with banners and trumpets.
And then no one ever wants to remove an unused or unprofitable feature. There is no bonus for it, no one puts that on their resume. But the feature you launched that really did enshitify the product gets put on there with 3 gold stars.
Re: How to write an effective software design document
#67I'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…
> At best, it helps to keep the business in sync at the expense of a much longer delivery timetable. If you're writing a software design document that slows down your delivery timetable, you're doing it wrong. (Or, more charitably, your business is doing it wrong.) If your design document is to keep the business in sync, you're doing it wrong. That's not what a design document is for. It's for keeping you in sync. >…
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 already been made?
Only slightly tongue in cheek.
Re: How to write an effective software design document
#68I'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 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 like.
Re: How to write an effective software design document
#69I'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.
In every single one of those, you are more concerned with the validation data than with high-level visions of your software.
Documentation is important for platform, and probably nothing else.
Re: How to write an effective software design document
#70Lot 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…
Referencing Joel Spolsky's article about how you should never do a rewrite is starting to feel outdated as well.
I think it's worth more scrutiny today, rather than less. Your claude code can barf out "a rewrite" but is it any good? So far the answer is "no" (see anthropic's C compiler, or a more recent port of bun).
Software is still the best specification for existing behavior..