My engineering team and I have been refining a simple structure for software design docs that I find to be remarkably succinct and effective as a planning and communication tool. It takes the form of a four-item checklist.
1. Purpose - review the business case.
Encouraging ourselves to put proposed implementations in terms of business requirements forces us to think practically and creatively about the trade-offs of what is often several proposed implementations. Because features take time to implement, review, and maintain, we save a lot of time and effort when we kill bad ideas quickly by considering them in a business context.
For instance, we find ourselves writing unnecessary proposals to make not-yet-validated parts of our business faster or easier. This section helps us remember to have the discipline not to work on things that don’t matter.
2. Proposal - outline the proposed solution or solutions.
If providing multiple possible solutions, the author should try to pick one that they think will work and explain why they are recommending it. More often than not, reviewers will disagree about what constitutes the most promising proposal. Sometimes an alternative or hybrid proposal will arise during discussion that works better. Sometimes none of the proposals gain consensus. In those cases, it’s always worth going back to the drawing board. The opportunity for early feedback and discussion generally makes for higher quality implementations.
3. Examples - work out some of the key details.
Giving an example or two helps people understand what the proposal or proposals describe. I think the adage about pictures applies here as well: an example is worth a thousand words. That said, sometimes less is more - an example is a sketch, and shouldn’t be a full blown oil painting. Details will almost always change after the document has been written and reviewed, examples are more important for communicating the main ideas than they are for being a precursor to the actual implementation. Sometimes it's better to wait for git diff than it is to try describing everything in prose.
4. Next steps - plan out action items.
This is an important bit often overlooked step that helps facilitate a quick transition from planning mode into execution mode. This is where we suggest details like who should be involved and how much time or effort will be required.
A few other pointers
Sometimes these components become the distinct sections in the document, but it's never a problem if they're a bit more integrated as long as they're all there in some form.
- Writing the design doc is a little bit useful for the author who is writing it, just like how writing a first draft of an essay will help you figure out your thesis, but the value multiplies when people start commenting on and suggesting revisions.
- Commenting should be asynchronous. If a lot of discussion is happening, consider a breaking that discussion out of the document and into a synchronous meeting. That meeting is likely to be a lot more productive than one that occurred without a design doc first having been written.
- If in doubt about whether or not a feature is "big enough" to require a design doc, err toward writing one. Lincoln (apparently) once said, "If I had an hour to chop down a tree, I'd spend 45 minutes sharpening the axe and 15 minutes chopping."
- I imagine the ideal structure will vary a bit from team to team. I think it was important for our team that everyone had a chance to buy into the process.
- Design docs should be quick and dirty.
Should design docs live on beyond the discussion?
As a team, we write so many of these that questions of the following sort have arisen:
- Should design docs be collected as some sort of history?
- Should design docs be updated to reflect comments or outcomes of discussions?
- Should design docs be used as feature documentation?
I think the answer to all of these questions is "no". Design docs should be ephemeral because their purpose is to foster productive discussion and guide initial planning. If discussion moves far enough away from the center of gravity of the document that a large update is needed, it's usually easier to start with a blank slate or just to jump straight to the implementation. I find that after the first round of discussion, code review is often more productive and relevant. Design docs are messy, littered with comments and usually outdated within a few hours of starting a real life implementation. But they're useful in the moment!