Technical-Writing

Technical design documents (TDDs) — sometimes called design docs, RFCs, or tech specs — are one of the most valuable tools available to staff engineers. When done well, they create alignment before implementation, surface risks early, and create a durable record of why decisions were made. When done poorly, they’re ignored, debated endlessly, or written as formalities after the decision is already made. This post is about writing TDDs that work: getting the right people to the right decision with minimum friction. ...

Most engineers write their first RFC by borrowing a template and filling in the blanks. The result is a document that describes a technical solution in detail, lists some alternatives, and ends with an open-ended question about what people think. That kind of RFC doesn’t produce decisions. It produces comment threads. An effective RFC is not a document that describes a solution. It is a document that frames a decision — that lays out the problem, the constraints, the viable options, and the trade-offs clearly enough that reviewers can evaluate them and reach a conclusion. The solution you prefer is in there, but it’s one item in a structured argument, not the whole document. ...

The RFC process is well-understood at most engineering organizations. You have a problem, you have a proposed solution, you write it up, you get feedback, and you either proceed or revise. RFCs are structured around a decision: should we do X, and if so, how? Strategy documents are different — and the difference matters. A strategy document is not asking “should we do X.” It is answering the question “why are we doing what we’re doing, and how does it connect to everything else we care about?” It is less about proposing a specific solution and more about establishing a shared understanding of the problem space, the constraints, and the reasoning that should govern future decisions in a domain. ...