Writing design docs

I generally agree though I prefer "decision docs" with a subtle difference: Only one decision per document. The article seems to always use "plural", so the focus of these documents is not a single decision but the design of a certain feature or subsystem.

The great point about decision docs is that there is need to maintain them. It was a decision made at a certain point in time under certain circumstances. If the circumstances change, one might adapt but that is another decision and does not modify the old one. The article states the same for design docs:

The document will drift out of sync with reality the instant anybody starts implementing the plan, but that is fine. The document exists to help future maintainers understand what their predecessors were thinking at the time.

“Plans are nothing. Planning is everything”

Maybe it's a personal thing, but I don't find thought-out documents to look rough. On the contrary, I think the "written for approval" documents look too polished; they're shiny toys. A thought-out document shows polish by having a good structure and conventions that are followed.

Edit: should have mentioned that on the whole, this is a great read, and I hope more people start to appreciate the reasons why documentation is important to write.