A software design document is a critical artifact for the development of new software or making significant changes to existing software. While we often think of the benefits of developing such document is to serve others (teach them about the system, document the system for future support), it actually benefits the engineer writing it the most by bringing clarity of thought and improving their design skills through feedback. Below I share four tips on what makes for a great software design document:
1️⃣ Problem Statement: One of the first things I look for in a design document is to get an understanding of the customer problem this software system design is solving for. How well does the engineer understand the problem, the domain etc. While this information may be present in other documents (such as business requirements doc), it's important here for the engineer to articulate it themself to ensure understanding. This is also an area where often times, engineers may go back to the product team and identify gaps in specification. An important part of this exercise is understanding the aspects of the problem that you expect to evolve over time, vs. invariants in the domain that you expect to remain the same. This in turn informs the flexibility and forward looking aspects of the design.
2️⃣ Design Choices: One of the key functions of the design document is to articulate the different alternatives that were considered and why we came to choose or recommend a particular choice (vs. these alternatives). It's important to share the mental model around these decisions for inspection during a review. Generally reviewers inspect the inputs that go into the decision, vs. the output which is very specific to the problem at hand. One of the misses I often see in documents is that they only showcase the outputs of decisions - which don't lend themselves to a constructive review session.
3️⃣ Non-Functional Requirements: Considerations related to non-functional requirements (e.g. availability, security, operations) are just as important to incorporate into the design than the functional requirements. These requirements can have a disproportionate impact on the design for systems running at high scale and serving business critical functions. In going through the design document, it needs to be clear to me that these have been considered throughout the design (vs. being an afterthought).
4️⃣ Change Management: The software design is expected to evolve as it gets reviewed, and also as work is underway. Be sure to track versioning of the design as well as high level summary of the feedback received and the ensuing changes. I generally like to see this at the front of the document as a page 0. This helps reviewer understand who else has seen the work and the feedback already provided - which makes for more efficient future reviews.
