- Insights
- Strategy
How to write a good Software Design Document
Tools
The best tool is a collaborative software program that allows many people to work on a common document.
Everyone involved in the product development should have access to this tool with the possibility of making comments or indicating improper fragments.
Confluence from Atlassian is currently the most widely used tool. Alternatively, you may consider Google Docs or storing editable files on a platform such as SharePoint.
For creating diagrams, I recommend using Gliffy (available as an add-on to Confluence and all popular browsers). I like it especially for ease of use and full integration with the other collaborative platforms.
Enterprise Architect from Sparx Systems is the other tool, popular especially in large corporations. Recently they have added integration with Confluence. It is a powerful tool and is used for complex work.
As alternatives for diagraming you may consider: UMLet, Lucidchart, ArgoUML, Visual Paradigm or Draw.io.
Some of them are available free of charge and you can launch them directly on your browser or Linux operating system.
General guidelines
Here are some general hints for achieving high degrees of clarity:
Apply plain language as much as you can. The doc should be easy-to-understand for every recipient.
Use short sentences and bulleted/numbered lists. Avoid long, complex descriptions.
Provide examples regarding real use cases of what you are trying to explain. For instance: The fee for performing this action is 10 EUR. If the user’s balance is equal to 9.95 EUR, then the change-icon is grayed-out.
Ask your colleagues for a review before finalizing the doc. Another person's point of view may be beneficial for the final result.
How to organize document structure?
An example structure of Solution Designs may look as follows:
Title
Name of the change specified by the document.
May contain Requirement or User Story identifier.
Contact persons
Contact details of the author and other people that may influence a shape of the solution.
Introduction
What is the purpose of this change? Why is it needed? Where does it come from? What will be the benefits of implementing this change?
Glossary
Specific (not clear for everyone) terms or phrases used in the document.
References
Links to external documents important for the implementation (e.g. specification of external interfaces).
The Impact on the other Requirements or User Stories.
Design specification
The high-level description of the solution detailing the modules that are affected by the change.
Describe As-Is (present) and To-Be (future) states of the system.
Include diagrams (UML or BPMN); ask the dev team which type of diagrams are the most useful for them.
Describe the significant business logic, e.g.: user flows, algorithms, data migration or conversion.
Specify a list of used interfaces with type (e.g. REST / SOAP) and usage context: new, updated, removed.
Changes in the database model (e.g. new fields in the user profile).
Annotated User Interface mocks.
Error handling
How to react on non-standard system behavior, such as downtime of backend systems.
Assume some nice-looking dialogs for every possible error case.
Non-Funcional Requirements
The potential impact on system performance, described in measurable values (e.g. the number of visits will increase by 10k per day; the demand for data storage will increase by 10 GB).
The impact on Data Security – is there a chance that improper implementation may cause a security vulnerability?
The impact on Data Privacy – does the solution entail changes in processing of personal data? If so, is the solution compliant with legal standards such as GDPR?
Out of scope
Functionalities that are intentionally descoped in the specification.
This may be the result of business decisions or a feasibility study.
Test Guidance
List of recommended test cases to be performed by QA.
Hints for the test data (e.g. specific users or tricky scenarios).
Open points
List of open issues.
Should contain the following: ID, name, short description, assignee and status (open / completed).
As long as the doc contains open issues, it should not be considered as the final version.
In addition to the chapters listed above, you may consider the following: Table of Contents, Release Notes (system configuration that must be done during production deployment), Risks, Alternative Solutions, Monitoring and Reporting Guidance.
Solution Lifecycle
As the system evolves, the design doc may become obsolete quickly. Therefore, it’s a good practice to keep the doc up to date. Such document may serve as a document that describes how the system currently works. It can be treated as an entry point for further system development. In addition, it is useful for troubleshooting and reducing the time required for system maintenance.
Pro tip – whenever you need to update an existing document with new requirements, proceed as follows:
While adding new parts – distinguish them for example with separate font color.
Strikethrough deprecated parts.
Once the new features are developed and released to production, unify formatting of the doc. You may also create list versions of your document with change dates and short description.
Summary
A good Solution Design doc is a mixture of business and technical knowledge served in a form that is easily digested. In order to become a master chef, you have to practice, collect feedback and constantly improve your craft. That’s the way to achieve the best outcomes.
