Writing a Good Design Document

Summary

How to write a good design document This essay is a version of the response I gave to my friend Vik's call for suggestions: Definition A design document is a technical report that outlines the implementation strategy of a system in the context of trade-offs and constraints. Goal Think of a design document like a proof in mathematics. The goal of a proof is to convince the reader that the theorem is true. The goal of a design document is to convince the reader the design is optimal given the situation. The most important person to convince is the author. The act of writing a design document helps to add rigor to what are otherwise vague intuitions. Writing reveals how sloppy your thinking was (and later, code will show how sloppy your writing was). Organization Good design document organization is as important as code organization. You probably have opinions about code organization. You've probably used the phrase "spaghetti code" to describe poorly-organized code. Most programmers write "spaghetti design docs" unless they've had a lot of practice. Let me illustrate a common code organization issue some programmers run into on their first day. The novice writes terminal.print("Hello world") Then they decide they want to make the text red, so they edit their program to terminal.print("Hello world") terminal.setPrintColor("red") And then they're confused that it didn't come out red. They haven't internalized that the first line of code happens before the second. They just get a soup of code on the screen that kind of has the ingredients for a program, and expect the computer to do what they want. Novice document writers make the exact same mistake, but with prose instead of code. They get a soup of sentences and paragraphs and expect the reader's brain to do what they want. If the reader is smart enough, you might actually get away with this. Just like an expert programmer can mentally untangle spaghetti code. But a perfect doc is written such that the reader is never ...