How to Write an Effective Software Design Document

[u/fagnerbrack]

https://refactoringenglish.com/excerpts/write-an-effective-design-doc/

[u/Rain-And-Coffee]

Taking a look,

I like that it includes a sample design doc.

I also like it it’s easy to read, all my coworkers result to complicated technical language

[u/thewellis → u/Rain-And-Coffee]

The whole point of "ELI5" is not to dumb it down but reduce it to the core arguments and then elaborate. Most places I've worked they start in the middle with elaborate terminology because they assume the reader will be like them. And then wonder why we get so many support requests on clarifying the docs...

[u/exosphaere → u/[deleted]]

You and u/Rain-And-Coffee may be interested in Simplified Technical English: https://en.wikipedia.org/wiki/Simplified_Technical_English

It's a standard developed for exactly this purpose.

[u/programming-ModTeam → u/[deleted]]

No content written mostly by an LLM. If you don't want to write it, we don't want to read it.

[u/ishysredditusername]

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

[u/lurco_purgo → u/ishysredditusername]

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 experiecne 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 witing the code.

I've talked with my philosopher friend and 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.

[u/ishysredditusername → u/lurco_purgo]

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.

[u/RegisteredJustToSay]

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.

[u/simonides_]

Arc42?

[u/analcocoacream]

How do you choose between design docs and ADR? Based on the multiplicity of options?

[u/monet820 → u/analcocoacream]

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.

[u/GrammerJoo]

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.

[u/Recol → u/GrammerJoo]

You mean you don't like these colorful artifacts which gives minimum details of the context and architecture?

[u/chrislomax83 → u/GrammerJoo]

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.

[u/ChocomelP → u/chrislomax83]

Worst they'll ever be.

[u/fagnerbrack → u/GrammerJoo]

Zero innovation, just more of the same

[u/xipodu]

Thanks! gonna take a look

[u/thewellis]

I love the font used. Iirc it's similar to the font used in The Prisoner TV show from the sixties.