I find design docs really useful, even if no one else reads them, because they force me to clarify my thinking before I start the (more expensive) process of implementation.
However, I've also noticed a couple of very common problems with design docs:
- Many design docs don't clearly state the problem that the design is intended to solve. Often the best response to a design is "that problem isn't important to solve", or "there's another system that already solves this problem", or "there's a totally different approach that you should consider", but without a clear statement of the problem and why it's important to solve, it's hard to determine those kinds of things.
- People often focus too much on the details of a design, vs. the important decisions that need(ed) to be made, the alternatives and rationale for those decisions, and the assumptions that they were based on. In a year, you probably won't care that much about the details of the parameters of some API, but you probably will care a lot about why you chose that API over some other one, and it's useful to have a record of that decision.
It's useful to view a design doc as a distillation of the thought process behind a system, vs. a high-level description of how to build something.
However, I've also noticed a couple of very common problems with design docs:
- Many design docs don't clearly state the problem that the design is intended to solve. Often the best response to a design is "that problem isn't important to solve", or "there's another system that already solves this problem", or "there's a totally different approach that you should consider", but without a clear statement of the problem and why it's important to solve, it's hard to determine those kinds of things.
- People often focus too much on the details of a design, vs. the important decisions that need(ed) to be made, the alternatives and rationale for those decisions, and the assumptions that they were based on. In a year, you probably won't care that much about the details of the parameters of some API, but you probably will care a lot about why you chose that API over some other one, and it's useful to have a record of that decision.
It's useful to view a design doc as a distillation of the thought process behind a system, vs. a high-level description of how to build something.