Does your upcoming project require a solution design document (or SD)? Then, make sure you continue reading this article because we will explain in great detail everything you need to know.
What Is a Solution Design Document?
A solution design document is a concise and clear technical document that a solution designer/architect typically designs during the phase of a solution development life cycle. This solution design document provides clarity for stakeholders. It shows them how their business requirements will be met. In addition, it serves to document an end-to-end software solution for specific projects. It also touches on various subjects like project challenges and risks, testing, design, and architecture.
A solution design is a blueprint of a software application system operating under functional and non-functional constraints.Mandy Masoom
As a software developer, when taking on a new project, before opening your IDE, you need to have agreed-upon and clear design goals. These goals should be contained in a document. If your client doesn’t write a solution design document, you should write one and submit it for review. Clients know the importance of a solution design document, and so you don’t have to worry about them rejecting the idea. The document itself doesn’t need to be lengthy, it can simply be just a few pages long, but it needs to include set completion milestones and wireframes.
Why Do You Need a Solution Design Document?
Without having a solution design document, you can end up in a loop of cutting and pasting previous conversations that you’ve had with a client, disputing what you have or have not told them, and interpreting what the client demands.
We all want a friendly relationship with our clients, and we want them to be satisfied. We all take pride in doing a great job. With this document, you can save yourself from angry arguments and misunderstandings with clients. In any case of disagreements with the client, you can refer to the solution design document.
Objectives of a Solution Design Document
Expected outcomes from a solution design document are:
The main goal is to provide internal and external stakeholders with sufficient confidence in the design. In other words, it assures them that business requirements are well understood.
Assisting the Developers and Testers
Sufficient details should be added on what source code changes are expected for the development team. Adequately covered, it will withstand plenty of adverse conditions.
By making all the data available in one document, engineers and testers can now make precise measurements of the required effort. This step is essential in removing any unnecessary remodelling in the future due to improper design.
WHAT is the Scope of Change, and HOW much Regression Testing is expected?
The SDD should answer those questions by capturing the impact analysis results. The impact analysis assesses the impacted components and the anticipated code changes. By this, we can mitigate any risk early in the project.
Inputs to the Solution Design Document
There are several inputs that can drive the design of a software system. Let’s discuss them in more detail.
The default way to communicate business requirements is usually with the Business Requirements Document (or BRD). Alternatively, clients now use Epics and User Stories in Agile methodology.
In this case, the role of SDD becomes crucial as it captures, in addition to the details of the design, a shared form of client requirements.
When we talk about future-proofing, we are talking about scalability, extensibility, and modularity. These properties are important if you want your application to last longer, increasing your ROI.
To achieve this, do your best to ensure that the new design will not be a heavy burden on the system unnecessarily.
Hardware and Infrastructure Considerations
Setting up new infrastructure is always such a complicated project because it usually requires a lot of budget and approval. In addition, many departments such as accounting, administration, procurement will be involved.
Be sure to include good amount details in the infrastructure setup. Also, consider all your environments from development to UAT, and finally, production.
Security and Compliance
Highly regulated industries such as insurance, health, and payments need to stay above their regulatory requirements.
It is possible that there will be a renewal of compliance with the largest to ensure their project. If you work in any of these industries, be sure to include safety and compliance details in your analysis.
Backward Compatibility and Regression Issues
Sometimes software has problems functioning in different web browsers.
To avoid any problems during product release, perform a detailed analysis of the impact on downstream systems. Most importantly, look for any related backward compatibility issues.
Mission Critical systems typically have a 99.5% uptime requirement. Businesses allow these systems to be reduced only by planned maintenance and/or upgrades. What this means is that any design error can be very painful when it goes live.
A solution design document should have the least elements:
- Milestones or Phases
- Criteria for completion
- Description of the desired application.
Qs to Ask
Some important questions you need to ask in the application design document are:
- What does the application do?
- What are the limitations if the user creates entries of any kind?
- What are one-time operations done at the first execution?
- What are possible failure conditions, and how will they be handled?
Be sure you go into great details with these questions because misunderstandings and errors can mean rewriting the code all over again.
At the beginning of the document, describe the project and its audience. For example, the audience might include project managers, technical staff (testers, developers, etc.), business analysts, and so on.
In terms of the user interface, give detailed descriptions of dimensions and constraints, error handling, the functionality represented, and supported orientations.
Milestones and Phases
Your solution design document should also present clear milestones. For example, if your client writes the interface and functional design, you should both agree on the milestones. Milestones can be in terms of components or functionality. Milestones should be roughly similar in duration if there is such a possibility.
Make sure that you perform a complete impact analysis and include all of the possible implications. Also, make sure you mention that all of the decisions were made during the product design.
To make sure that the solution design document is clear enough, ask yourself the following questions:
- Are there any open questions left?
- Is there enough data (visualisations, text, etc.) to help adapt the more complex ideas?
- Are there any constraints on the future evolution of the product that was placed by design?
- How were the conclusions reached, and what are the key decisions taken?
- What are the expectations from different stakeholders, both external and internal?
- If the designer is on vacation for a couple of days or weeks, can the project still be smoothly carried out?
- Will the proposed changes cause any integration problems with the ecosystem?
- What other functionality (user experience, reports, data, features) will be modified or impacted by the change?
- Have the risks on customer experience, service availability, timeline, and budget been properly tabulated?
Easy to Read
This document should be free of ambiguous statements, so make sure you are precise with the formulations of sentences. Also, make the document easy to read. Short sentences and structured paragraphs will allow the reader to quickly go through the document. Avoid grammar mistakes, sentence fragments, and typos.
To help the reader easily go through the content, add as many visualisations as needed: tables, diagrams, and other visualisations.
Make Sure Your Solution Design Is Relevant
Once you and your client agree on a solution design document, it doesn’t mean that the design phase is over. When you and your client look at the intermediate results, you will both find flaws that you didn’t expect, design changes, and new ideas you would like to implement. Your document should be relevant, and the changes and evolution of design should be contained in your document.
What’s important to remember is to keep in touch with your client. Contact your client several times a week, make sure you share the same idea, ask for clarification if you aren’t sure about something, and generally report how the project is going.
Determine where your solution design document will reside and determine who will be responsible for maintaining the solution design document in your organisation or business. Also, decide on the location and ownership of the design document. Typically, solution design documents are placed at a widely accessible location, like collaborative workspaces like Google drive or a shared cloud drive.
Further to Go
- Here you can find a comprehensive detail on Solution Design Documents: What You Need to Know