Reasons to Write Design Docs

[zdw]

https://ntietz.com/blog/reasons-to-write-design-docs/

[aschearer]

+1 to design documents. Would add another reason they're useful: reducing miscommunication & misunderstanding between stakeholders. In my opinion, a tech document's goal is to uncover missed specs, invalid assumptions, broad architectural errors, if we're actually prepared to build (i.e. can we speak credibly to what/how), and finally to reduce miscommunication between various teams/disciplines.

I'll add I think tech doc review is just as important as writing stuff down. In my experience it's often done poorly. Doc should be ready ahead of time, sent to relevant people, read ahead of time, and a list of open questions and comments seeded before the meeting. The meeting should have a notetaker. The meeting should be shorter rather than longer. Have fewer people rather than more. The meeting should not be about reading the document top-to-bottom, but about answering open questions and confirming everyone is on the same page.

[Avisan]

That's a great article on the importance of writing design docs!

I especially appreciate the emphasis on how writing can improve your thinking and collaboration.

Thanks for sharing your insights!