I like the idea of design documentation, but in 30 years of software development experience, I've never seen one done well. TFA does a reasonably good job of outlining what you'd want from an ideal design document but doesn't offer any advice on creating one that actually meets these criteria.
One trick google uses is that there are 'standard' templates to start your design doc from. So it has all the sections mentioned in the post, and each section is initially filled with a description of what is needed there (and sometimes links to other supporting materials).
Not everyone will be diligent and fill out all applicable sections, but it does help bring some uniformity to the process.
I think forcing a team to ask these questions is more important than making the document perfect. I've had too many conversations that amounted to "a React front-end, Node backend, Mondo data store is the perfect solution to this and every problem," with no other options chosen.
There's also value on having some this kind of documentation when you're bringing on new people. The project I'm currently working on started two years before I got here, and I would love to have a document that explained why, for example, we're using Active Directory instead of some other authentication mechanism.
Basecamp pitches and shaping are kinda like design docs but with a lot of what I found to be lacking here? You might want a look, they they refreshingly human-readable concepts.
But code actually works (eventually, usually). If you don't have code, you don't have software. If you don't have a design document... it's usually the same as if you do have a design document.
In my experience, it’s not the same. Design docs allow a dialogue about the resulting code that code reviews are poorer at or less efficient at. Those conversations have saved us time and gives us confidence that the solution is the best for the problem.
