The reasons for design documents

This resource first appeared in issue #33 on 17 Jul 2020 and has tags Technical Leadership: Other, Managing A Team: Documentation/Writing

Design Documents at Google - Malte Ubl
Code only says what it does - Marc Brooker

Malte Ubl’s article is a nice overview of how design documents are done at Google, and how they are used - to communicate not only an end goal but the why’s - the context, the tradeoffs intentionally made in design, and the alternatives considered.

As Marc Brooker’s article points out, code is great and can be “self documenting” at what things actually do, but not why they are done that way. Without information like what tradeoffs were chosen and alternatives considered, it’s hard to know whether or not the old why’s are still valid and so whether or not change is needed.

(Design documents are not especially new things - e.g. decision logs have been a part of project management for ages, for similar reasons.)