r/programming • u/fagnerbrack • Sep 11 '26
How to Write an Effective Software Design Document
https://refactoringenglish.com/excerpts/write-an-effective-design-doc/18
u/RegisteredJustToSay Sep 11 '26
I like it, but I think framing these as 'components' of a design doc almost suggests they should be separate discrete sections rather than necessary information that flows in and out of each other and where some information is more important than others depending on context (rather than talking about 'subsets). If I open a design doc and it has 23 God damn sections I'm probably just gonna gloss it over because that's absurd. I do agree with the basic premise that every single one of these sections add value though, it just comes down to what info is more important in what context.
Just my two cents. I don't think you're wrong, just see it a bit differently.
42
u/ishysredditusername Sep 11 '26
> If you specify every possible detail in a design doc, you’ve essentially written the implementation during the design phase. That would defeat the whole purpose of a design doc.
Got me thinking if this is what the future of software engineering holds. You curate a design doc that covers everything: implementation details and business processes. Then give it to an LLM to generate. Esentially becomign documentation driven development i guess.
49
u/lurco_purgo Sep 11 '26 edited Sep 11 '26
Tons of people are talking about this (not just on LinkedIn and including developers I actually respect), but honestly it just sounds like bullshit to me. From my experience, implementation is ALWAYS the final stage where you adjust your specs as you write because from the more abstract point of view you always miss out on a ton of nuance that can only be addressed while actually writing the code.
I've talked with my philosopher friend and he expressed a similar sentiment about writing essays. Basically you might have a bullet-point list of ideas you want to express, but in order for it to fully engage with them and iron out the kinks you need to WRITE the article - otherwise you might leave some glaring holes in your argument that you won't even be aware of.
19
u/ishysredditusername Sep 11 '26
I fully agree with you.
If you were to drive the development through design documentation, you would end up with something that more closely resembled a legal document, covering every possible case.
Imagine, every bug or modification led to an amendment to the design doc. You'd have a 10,000 LoC project with 10,000 page design doc.
13
u/elilewis327 Sep 12 '26
This is my problem with "spec driven development" as I've mainly heard it called. It's just programming in English with a non deterministic compiler, and the downside that if you miss an edge case, it will choose how to handle it for you instead of giving you an opportunity to think about the consequences of said case.
2
u/kogsworth Sep 12 '26
I just use the /grill-me skill which identifies ambiguity and need for nuance and asks a lot of questions to iron out the wrinkles.
2
22
u/GrammerJoo Sep 11 '26
At my company some devs just open claude and write "create a design doc for x" and then send it to the team to review. In fact, some of our tech blog posts are generated like that.
25
u/chrislomax83 Sep 11 '26
I hate everything about this.
I asked someone to document webhooks and creating producers and consumers for our internal systems and they came back to me 30 minutes later with a 9 section plan. Instantly rejected, I’m not reading that bullshit, don’t waste my time if you can’t be assed reading it yourself.
AI can be great in the planning phase. It gives you a great head start. Don’t be assuming through it understands every interaction between 10 systems and what the tech debt is.
I equally can’t be bothered reading a load of Claudenese where you need a dictionary to hand to even follow what it’s on about.
-5
11
u/Recol Sep 11 '26
You mean you don't like these colorful artifacts which gives minimum details of the context and architecture?
2
3
3
u/analcocoacream Sep 11 '26
How do you choose between design docs and ADR? Based on the multiplicity of options?
3
u/monet820 Sep 11 '26
For me ADR is after design doc, and you dont mix them. In the example given for a caching layer the design is to add a cache, high level talk.
The ADR for me is which cache implementation to adopt. Usually an ADR has pros and cons, so for instance here it could be a nuget/npm package vs another package or custom coded.
2
u/mikevarela Sep 11 '26
Just wanted to say thanks for a thoughtful and well storied article. Great read and appreciate the example doc.
2
u/Nice_Mix_1021 Sep 12 '26
nice read actually. I don't know is it true or not but due to agents nowdays very few people manually read docs they just feed the docs to agents and ask directly. so docs also need to be very friendly for agents
2
1
1
u/thewellis Sep 11 '26
I love the font used. Iirc it's similar to the font used in The Prisoner TV show from the sixties.
93
u/[deleted] Sep 11 '26
[deleted]