What is a design document?
In software engineering, a design document can be defined as a document that describes a technical solution to a (most likely business) problem.
Sounds like a waste of time. Can I get coding instead?
You could start coding directly, but it would be a very disorganized process, especially if you’re looking to deliver through a team.
The advantages of writing a design document are manifold. A design document is a good way to:
Disambiguate the problem space in your own head. If you’re solving a complex, ambiguous problem, writing about it helps bring clarity even to yourself.
Get your senior management to buy-in to your proposal. Explaining what business problem you’re going to solve and how you’re planning to do it is a great way to influence without authority.
Get feedback from your colleagues. Can you imagine asking for a code review without writing the code first? Write down your design so that your colleagues find it easier to find gaps and suggest improvements to it!
Deliver through others. The document gives your team the overall context of the initiative, making them less likely to need handholding through the implementation process.
Make it a living document that describes your system - one that new joiners can use in their onboarding process.
Know your audience
Apply the concepts from my previous article Decoding Expertise - know who is going to read your document and explain yourself in the simplest terms possible.
The secret sauce to making it flow
Use the following general structure to make your document flow like a story:
Start with “Why”: Why are you proposing to build the solution? This section should describe, in brief, the business problem you’re trying to solve. Stay away from the “how” in this section. (e.g. “The average time a customer service rep spends on paperwork after each call is 4 minutes and 43 seconds. This document describes a solution that automates this process and saves up to 95% of this time, allowing the rep to attend 23 more calls per day”.
Current state and pain points: Describe the current state of affairs, and current system if any. Explain in detail what the pain points with it are, where it falls short.
Requirements for the new solution: The gaps and pain points from the previous section form the basis for the requirements for the new solution.
Proposal overview: This is the section where you start describing your design. Add an overview of your solution here along with the high-level architecture diagram. State briefly what the various components are and how they will interact with each other.
Details: Describe each component next - its function, backing technology (is it a service/lambda/queue etc) and its role in the overall architecture.
Appendix: This section plays a major role in keeping the main document short and digestible. One of the must-haves in this section is the alternative designs and technologies considered, and the rationale behind picking the options described in the main proposal. Use this section for any other info that would be too much for the main document to include.
Additional tips
Keep it crisp: Try and keep the reading time under 30 minutes, which for a technical document is usually < 3000 words. This will ensure better engagement and feedback.
Keep it at the right level of detail: A design document should describe components at the architectural level, not at the coding level. (Think APIs and contracts, not coding language)
Et voila! You have told a story with your design document! Happy writing ❤️
Excellent post, thanks for sharing.
I really love this: "Start with “Why”: Why are you proposing to build the solution? This section should describe, in brief, the business problem you’re trying to solve. Stay away from the “how” in this section." - too many documents are just the how without the crucial context that the why provides.