In his blog Why Engineers Need To Write, Ryan Peterman writes about the importance of writing in engineering.
Almost everything software engineers do requires writing. We need to write when we ask technical questions, comment on code reviews, or create design docs. This is because writing software is collaborative. The better you are at writing, the more effective you will be at building software.
This let me to write and share this essay on On Design Specs (and Why Engineers Need To Write).
On Design Specs and Why Engineers Need To Write
Writing design specs typically helps improve the chances of having a successful software implementation and thus a successful delivery. As a forcing function, writing design specs help software engineers think through the software designs and architecture to be implemented, share design alternatives, and expected operationalization aspects. It also let the developer think about the dependencies and risks, and to form a work-breakdown ahead of the implementation itself. Design specs also help others understand a proposed software design and implementation, and provides for a mechanism to collaborate and receive feedback from peers and stakeholders. Lastly, it provides documentation for future reference and projects.
It is highly encouraged to write design specs especially for complex implementations that require research and early feedback gathering. Deciding when to write a design spec is more of a judgment call, but design specs should be written for complex-enough software projects that include complex frontend and backend implementations and interactions, backend API/Services or micro-services, complex features and algorithms and data models, and new areas of development or new areas for the developer. Sometimes it is a good idea to create a Proof of Concept (POC) together with a design spec, all as part of a Spike.
Design Review Process
Once a design spec has been written, it should be reviewed with peers and stakeholders. As mentioned above, design specs help you think through and define how a problem will be solved, and it help others understand a proposed software design/implementation before writing code. Design specs provide a mechanism to collaborate and receive feedback from peers and stakeholders.
In the software development lifecycle (SDLC), a design spec should be written and reviewed before implementation takes place. In this phase, a software engineer captures a design proposal and reviews it with peers and stakeholders for collaboration, feedback, and approval by the team. Design reviews can be informal or formal with a meeting. Face-to-face design reviews are high encouraged to ensure deep collaboration and feedback.
The design spec document should also capture comments, feedback, design adjustments (which may require re-designs and re-reviewing the spec), as well as design architectural decisions and approvals. If multiple design alternatives are proposed, the selected design is marked as [SELECTED] and the alternate non-approved designs are moved to the appendix for historical documentation purposes.
Design Specs Across Teams
It is up to the team to decide if it makes sense to combine or break up the design spec per area, for example, across frontend, backend, and data modeling. Maintaining a single design spec with sections for each area or team helps keep all related information together, and minimizes the number of documents. But again, it is up to the team to decide how to keep related design specs together.
Design Specs Location
Design specs should be placed under a common place. One top is to organize your design specs by area or product, and by year.
Improving the Process
Processes need to be flexible. Allow for the ability to adjust or improve the design spec and review process as needed over time. Share your feedback with the Scrum master and or use the Retrospective meetings at the end of every iteration for ways to improve the process for the next iteration.
Design Specs Content
What information should a design spec contain? The index below shows the different sections that a complete (long-version) of a design spec should include. This template I have evolved over many years. You can make a short version of it, depending on the design complexity and scope.
- What Problem are we Solving?
- Overview
- Related User Stories (Scope)
- High-level Design and Architecture
- API/Endpoint Design
- Network Design Considerations
- Database Design and Migration Considerations
- Security and Privacy Considerations
- Error Handling
- Constraints and Assumptions
- Dependencies
- Risks and/or Concerns
- Validation and QA
- High-Level Work breakdown
- Appendix – Alternate Designs
- Appendix – Timeline Considerations
- Appendix – Observability, OE Metrics, Alarms, and Dashboards
- Appendix – Standard Operating Procedures
- Appendix – Deployment and Operationalization
- Appendix – Cost of Operations
- Appendix – Capacity Analysis/Impact
- Appendix – Resources and Links
- Appendix – Questions and Answers
- Appendix – Reviewers/Approvers
- Appendix – Other