Design documents: maybe the only record of what the hell you were thinking
A difficult problem in engineering is building things that work with the things everyone else is building. Design documents are one way we share information, to make sure everyone is going in the same direction and to have ideas reviewed before they become code. The more context they have, the more useful they are, both immediately and later on.
Most design documents I've seen have an author, a short overview of what the goal is and a detailed design section. That's enough to show what you're planning to do, but it doesn't come anywhere close to sharing all of the context that's in your brain when you're writing it. Here's a bunch of other information that makes a design immediately more useful:
At least one date. The most useful one is when the document was last updated -- that tells how fresh it's likely to be -- but the creation date might be useful too if this thing is going to be updated over a long period of time.
What the status of the design is. Do you currently want comments? If you've moved past the review stage and are implementing, or have already launched or abandoned this idea, save your readers some time and write that down.
What you want reviewers to do. If the document is out for review, be honest about where you are with it. Are you looking for someone to poke holes in your core premise? Are you mostly clear on the direction but want more eyes on the details? Have you already decided what you want to do and this document is just a formality? Spell out what kind of review you want.
Tell people if you want them do explicitly say they approve of the document, or you'll likely get drive-by reviewers who nitpick a point or two, but don't comment on the overall premise of the design. Some design authors will take the absence of blocking comments as enthusiastic support. Others will wait uncertainly, wanting someone else to agree that the design is good. I like to list a set of approvers whose opinion I care about and note that I'll start implementing when all of those people say yes, this is a good plan. I ask the approvers to leave a high-level comment on the document like:
Approvers should say yes or no, or be clear on what they feel is missing. Or declare that they don't care and don't want to be an approver. Either way, you know where you stand!
Why you're doing it this way. What existing code or systems almost solved your problem? What other approaches weren't as good or didn't meet your constraints? Even if it seems obvious now, write it down once, rather than having people ask "But why..." forever. You may even save someone from getting most of the way through trying a "better" solution before discovering the same roadblock that you did.
Why you're doing it at all. Finally, the reader needs context on why this design is worth anyone's time. The "5 Whys" model is often used to understand problems, but I think it's great to keep asking ourselves "why" for designs too, and write down the answers. "Our objective is to build a new Foo server" "Why?" "It moves the functionality out of Bar" "Ok, but why?" "It means we can shard Bar" "Why?" "We're hitting scaling limits and it's making Bar run slowly" "And that's bad because?" "Users are getting occasional timeouts when trying to buy things in our store and they sometimes don't come back so we're losing sales". Keep asking why until it gets down to users or money or missing an SLO.
Sometimes the design is not about solving an existing problem, it's necessary for some other exciting goal. I think of these kinds of designs like the technology tree in Civilization. Maybe we're not really invested in one particular technology; it's a stepping stone on the path to another one. Maybe we have a design for Bridge Building, but we're not actually trying to build a bridge, we want to combine it with our Steam Engine abilities so we can get Railroad.
If this is a technology tree design, spell out in the design document that you're really working towards a Railroad. If your coworkers think everyone is focused on Explosives and Metallurgy, it's better to find out now.
[Banner image: picjumbo_com at pixabay]