P2E Pro Pvt. Ltd.
Solution Design Document Overview
- Padma Swaroop (Unlicensed)
- Akash Srivastava (Unlicensed)
Architecture vs Design
Architecture and design are two terms that are often used interchangeably in software dictionaries, but they have different meanings.
Architecture involves creating multiple concepts and selecting the best one that meets project and technical constraints.
A solution design optimizes solution parameters to provide excellent business value (functional and non-functional business requirements) at the lowest cost (implementation, maintenance, and operation).
While architectural plans are treated in the High-Level Design, an LLD (Low-Level Design) focuses on the low-level technical decisions (data model, design patterns, code areas impacted), implementation (algorithms, pseudo-code), and their impact (validation and testing).
It is crucial to distinguish architecture from design, especially when selecting the topics to tackle in a Solution Design Document.
Product vs Solution
Product and solution are not interchangeable terms, as they have different meanings.
A solution design consists of multiple integrated products, platforms, or third-party systems to provide an end-to-end solution for customers.
A product is a tool or service that provides a specific functionality of interest to the client.
Conversely, a solution is expected to address the customer's business needs by integrating multiple products into a working whole.
Products interact with each other, end-users, and the environment through interfaces within the solution.
A Solution Design Document must cover the entire solution end-to-end, avoiding a narrow focus on a subset of products.
Definition of a Solution Design Document
The Solution Design Document is a technical document created during the Design Phase of the Software Development Lifecycle.
It is produced by a solution architect and reviewed by technical stakeholders, including developers and business analysts.
The Solution Design Document's objective is to document an initiative's end-to-end design, including impacted business use cases, code modifications, the scope of testing, project risk, assumptions, and technical decisions that change a product's features.
The Solution Design Document aims to provide stakeholders with a clear understanding of how their business requirements will be met.
The document includes enough details to allow for precise effort estimation and the creation of a detailed project plan.
The Solution Design Document helps ensure that all stakeholders are aligned on the initiative's technical details and are aware of any potential risks or challenges.
It serves as a blueprint for developers to follow during the implementation phase, ensuring that the solution is built according to the intended design and completed within the desired timeline and budget.
Contents of a Solution Design Document
The following infographic shows five topics a typical solution design document must tackle.
A well-written Solution Design Document provides a detailed and comprehensive view of the solution's technical details, ensuring that all stakeholders clearly understand the solution's implementation. A solution design document covers the following topics:
Software customizations supporting functional requirements
The Solution Design Document covers software customizations that support functional requirements, including design decisions, code or interface changes, algorithms, pseudo-code, operational guides, training material, reference documents, and data models that support the business requirements specified in the BRD (Business Requirements Document)
Technical design supporting non-functional requirements
The document also covers technical designs that support non-functional requirements, such as hardware and software changes. Close collaboration between the architect and senior developers can identify the necessary changes.
Third-party software
The Solution Design Document includes a section on third-party software, which covers all third-party software, libraries, frameworks, interfaces, licenses, and APIs provided by external vendors that may require testing or integration effort.
Hardware
The document includes a section on hardware changes, which lists all hardware or hardware-related changes required for the solution.
Configuration and data
Configuration and data are also covered in the Solution Design Document. Configuration changes involve modifying parameters that allow integrators to modify features' behavior without changing the code. The document must also cover data changes, including data insertion, updates, or deletions from an application's database, which may cause behavioral changes that require quality assurance and, therefore, must be documented.
Objectives of a Solution Design Document
The Solution Design Document should achieve the following objectives:
End-to-End Design
The document should provide a comprehensive view of the end-to-end design, documenting every major technical decision with supporting evidence to ensure consistency and completeness in the implementation.
Stakeholder Buy-In
The document should provide clarity to stakeholders, allowing them to be involved and committed to the implementation. It should help them understand the implications of the solution and gain their buy-in for successful implementation.
Impact Analysis
The document should describe the impact of the technical, operational, and functional changes that will be applied to the system. It should enable effective preparation by developers, testers, DevOps engineers, and end users.
Project Risk
The document should clarify uncertainties, highlight potential risks, and provide a coordinated strategy to mitigate threats with various risk management techniques. It should help decision-makers prepare for knowable eventualities and avoid service disruption and financial or reputational damage.
Project Scope
The document should list all system changes expected to be delivered in the project to defend the project scope by providing project managers with enough information to distinguish current and new change requests.
Project Cost and Schedule
The document should include a thorough analysis of every change to be implemented, allowing project managers to produce a detailed plan with explicit dependencies, tasks, and subtasks. It should enable estimating effort, including contingency, to produce a precise project cost and schedule.
Other Components in a Solution Design Document
1. Overview/Introduction
2. Documents Scope
A good document begins by defining its scope.
For example:
Scope: This document describes the design of Project Frambus.
A better document additionally defines its non-scope—the topics not covered that the target audience might reasonably expect your document to cover.
3. State your audience
A good document explicitly specifies its audience.
For example:
This document is aimed at the following audiences:
1. software engineers
2. program managers
Beyond the audience's role, a good audience declaration might also specify any prerequisite knowledge or experience.
For example:
This document assumes that you understand matrix multiplication and the fundamentals of backpropagation.
4. Summarize key points at the start – First Page to catch the reader’s interest.
5. Define your audience's needs
Answering the following questions helps you determine what your document should contain:
Who is your target audience?
What is your target audience's goal? Why are they reading this document?
What do your readers already know before they read your document?
What should your readers know or be able to do after they read your document?
For example, suppose you have invented a new sorting algorithm similar to quicksort. The following list contains some potential answers to the preceding questions:
Who is your target audience? The target audience consists of all the software engineers in my organization.
What is your target audience's goal? My target audience wants to find more efficient ways to sort data. They are reading this document to determine whether this new algorithm is worth implementing.
What do your readers already know before they read your document? My target audience knows how to write code and has previously studied sorting algorithms, including quicksort. However, most people in my target audience haven't implemented or evaluated a sorting algorithm in several years.
What should your readers know or be able to do after they read your document?
My target audience will be able to do all of the following:Understand how the algorithm compares and contrasts with quicksort.
Identify the two kinds of datasets for which the algorithm outperforms the quicksort algorithm.
Implement the algorithm in their choice of programming language.
Identify the two edge cases in which the algorithm performs poorly.
6. Requirement Details
A breakdown of the new requirements with comments and discussions. It helps determine which requirements are already met, excluded, or require further clarification.
7. Assumptions and Prerequisites
This is an integral part of the design process. Its purpose is to ensure that everybody is clear on the foundations of the design. It will also allow an early assessment of whether these assumptions are valid, acceptable, or require a review.
8. High-Level Design
This section aims to provide process flow updates and information pathway changes using diagrams, tables, and other visualizations. Typically, also addresses integration issues with other systems.
9. Low-Level Design
This can be achieved via flowcharts, pseudo-code, and flowchart diagrams. The aim is to pinpoint expected source code files, data model tables, and functions to be modified. It will also give testers an idea of the scope of change and help drive the overall testing effort. This section equally covers exception handling and negative scenarios.
10. Impact Analysis
Discusses the impact on existing versions of the product already in production. It also discusses any possible degradation or interruption of service after the upgrade.
11. Out-of-scope
Essential for a mutual understanding of what will not be covered in the current project. It helps avoid misunderstandings and potential "free work".
12. Risks and Mitigation
Risks can arise in the form of:
External dependencies on the availability of third-party components in the form of software modules, specifications, feedback, resource availability, etc.
Regression issues are introduced due to work on legacy, poorly documented, or badly designed systems.
Incomplete requirements require decisions to be deferred until after the project has started.
Any missing or unavailable prerequisites for coders, testers, or operations such as tools, test environments, etc.
13. Appendices
Additional information that could be too detailed or not strictly relevant to the topics discussed. It can be presented for completeness and clarity.
__________________________________________________________________________________________________________________
References
Information used to compile this guide is available at the below URLs:
https://skyhighsoftwareengineer.com/the-purpose-of-the-solution-design-document/