Need to write a Solution Design Document (or LDD for Low-Level Solution Design) for your upcoming project? This article will equip you with a comprehensive set of tools to guide you through the process.
The design phase of IT projects is an integral part of the Software Development Lifecycle, and just like any other stage in the process, it involves producing quality artefacts.
Without quality outcomes, any subsequent dependent steps will suffer. Quality outputs like documentation and other artefacts are essential requirements for superior, smooth-running processes, perfecting your deliveries, and strengthening your value proposition.
A couple of notes, however, before we move on.
1.1 Not Sure What Solution Design Is?
If this is your first time creating a solution design document, or perhaps you are not entirely sure what designing a solution involves, we recommend that you go through this article first.
It will provide some context on the subject and layout the groundwork for the present article. It will also explain why designing a solution before implementation is vital for the success of any project.
1.2 What’s a High-Level Solution Design (HLD)?
In this article, we focus primarily on the Low-Level Solution Design (or LLD) and how to document it. If, instead, you are after a High-Level Solution Design (HLD), make sure to follow that link.
1.3 Solution Architecture vs Design
Depending on the nature of your IT project, and the delivery method you adopt, you might find investing in solution design documents a vital piece of your delivery process.
In the coming sections, we look at:
- The purpose of having a documented LLD
- What does a Solution Design Document involve
- Tips on writing excellent technical documentation
- A handy and straightforward Solution Design Document template
2. Table of Contents
- 1. Overview
- 2. Table of Contents
- 3. What Is a Solution Design Document (LLD)
- 4. Value of Having a Solution Design
- 5. Addressing Project Constraints
- 6. What Does a Good Solution Design Document Look Like?
- 7. Solution Design Document Template
- 8. Conclusion
- 9. Featured Articles
3. What Is a Solution Design Document (LLD)
Let’s go over a few key concepts that define a solution design document.
These concepts are as follows:
- An LLD is a clear and concise technical document
- Created by a solution architect during the design phase of the SDLC
- That documents an end-to-end design for a software solution
- And whose aim is to provide stakeholders with enough clarity on how their business requirements will be met.
A typical solution design document usually involves detailed information on the following system topics:
- Software: includes detailed low-level feature requirements and implementation details such as specifications, algorithms, process flows, diagrams, tables, code changes, or pseudo-code.
- Hardware: lists all hardware, and other hardware-related requirements or configuration changes. May include additional servers, network devices, licenses, cloud subscriptions or services, and specialized equipment.
- Low-Level business requirements describe component requirements in enough detail to allow the development and software testing and verification to be completed. Functional requirements describe how the software works, while non-functional requirements correspond to security, quality, and similar considerations.
- Project-specific new or updated configuration data: this information helps developers, testers, and DevOps engineers apply and validate application configuration changes during their tests.
Solution design documents generally cover the following areas:
- A detailed list of business features (should map into a business requirements document or BRD) or any other work to be done
- Architecture and design considerations
- Solution implementation details and any technical decisions made
- Impact analysis of the updates or new features.
- Software testing requirements such as updates required on automation tools or test scripts, and
- Finally any project technical risks, challenges, and mitigation.
The typical audience is formed mainly of technical people.
3.2 Product vs Solution
People sometimes use the words product and solution interchangeably but that is not very accurate. I have provided a comparative analysis of product vs solution. If you want to have the full details, you can follow the link.
For the purpose of this discussion, we can summarize the product vs solution discussion with the following words:
In contrast to “product”, which can be defined as a tool or service that delivers functionality of interest to the client, a “solution” is expected to solve the customer’s problem(s).
4. Value of Having a Solution Design
The following list summarizes the aim of having a solution design document:
- Document all the essential components of your software solution and their specifications and design parameters. These could be hardware, software, or application.
- Describe the significant technical changes applied to your system or application. Any change that might impact how the system functions or operates will need to be explained appropriately.
- Explain the technical project risks like those involved in going live with the new changes) and challenges that can be expected and list the different mitigation options available.
- Detail the large to medium-sized implementation changes to help developers, testers, and DevOps engineers efficiently perform their job without constantly looking for clarifications.
- List what’s in-scope and what is out of scope to lock the scope and prevent scope creep.
- Document all the technical decisions made along with supporting arguments
4.2 The Value of Good Documentation
There is an adverse view among professionals, especially Agile proponents, on the necessity and validity of extensive documentation and whether perhaps we can do without it.
Our view is based on the following rule: achieving Operational Excellence in Software Delivery requires identifying those processes and their outcomes that generate business value. If the business value of having solution design documents is demonstrable, it must be part of your SDLC processes.
Investing time and effort in the design and documentation of IT solutions is one of many tools to help you achieve smooth deliveries in high cost-of-change projects.
The risks of poor design processes are:
- Unclear requirements leading to unusable software
- Designing on-the-fly
- Costly feature rework
- Insufficient or inappropriate software verification and validation
The key idea is to identify the appropriate quantity and quality of good documentation for each project.
4.3 Desired Outcomes
Check the below image to see the expected outcomes from a solution design document. We will cover each of these in the next sections.
Let’s review these items one by one.
- Stakeholder Buy-in
The primary objective of an LLD is to provide internal and external stakeholders with enough confidence in the design so that they can provide their inputs and ultimately buy in.
- Clarity on Changes
Include enough details for the development team to understand what source code changes are expected. Use pseudo-code if required.
When changes are properly documented and the programmers avoid having to design on the fly. Developers and testers can now make precise estimations of the efforts required.
Using the valuable information on expected changes, Project Managers can prepare detailed implementation plans. Remember, we are still at the design phase of the SDLC!
furthermore, developers and testers will have a solid foundation they can lean on to start writing their test cases. This information is vital when applying Test-Driven Development (TDD), a practice that we highly recommend.
This step is crucial in eliminating any avoidable future rework due to poor design.
- Impact Analysis
By far the dearest topic on the software tester‘s heart: what is the scope of change, and how much regression testing is expected.
In large, complex, and mission-critical solutions conducting an Impact Analysis exercise will help you mitigate the risk of dangerous side effects. It will help you determine those features that have been impacted by the change and will need to be tested for regression problems.
The LLD should answer those questions by performing impact analysis on the anticipated code changes. A bidirectional traceability matrix is an excellent tool for achieving precisely that.
If you do not wish to perform this, you must have automated testing that allows you to get full coverage with on-demand testing.
- Evaluating and Mitigating Risk
Risk generally comes from a project’s known or unknown unknowns such as changing requirements or adverse side effects. Use the impact analysis to evaluate and mitigate any risk early on in the project.
Use your expert knowledge to determine whether any risk when deploying the changes to production is anticipated.
5. Addressing Project Constraints
Designing a proper solution helps you deliver an application that the customer wants to use. Customers are usually happy to compensate you for your efforts if they can derive value from your products. Therefore, your products must address their business needs.
Customer needs are usually communicated in the form of business requirements. These can be viewed as multiple and often conflicting constraints.
Designing a solution is essentially an optimization process whereby a solution designer or architect finds a technological solution that offers maximum value at the lowest cost.
The best and most familiar example of project constraints is time and money. The customer typically wants top value delivered within a specific budget and timeframe.
A solution design document brings all these constraints together in one place and allows you to understand the mutual impact of one another.
The above diagram shows the solution design process with inputs, outputs and external requirements and constraints.
Some external constraints like security or compliance might be catered for already within the business requirements documents. In some cases, however, an industry-grade application is expected to conform to regulatory requirements and industry best practices without explicitly listing them in any business requirements document.
5.1 Business Requirements
In case a BRD is not available, the LLD needs to capture, in addition to design details, a mutually acceptable form of the client’s requirements.
5.2 Hardware and Infrastructure Considerations
Buying new hardware is always such a project because it usually requires budgeting and many approvals.
In addition to that, many departments such as accounting, management, and procurement will be involved.
Hardware is Not Just Servers! It can also be specialized equipment, network components, cabling, racks, licenses, support, administration, and significantly extra space in the data centre.
Be sure to include a generous amount of detail on the hardware setup. Also, cover all your environments from development to UAT, and finally, production.
5.3 Future Proofing
Future-proofing in technology is never guaranteed. We can, however, do our best to ensure that what is implemented today is flexible, modular, and scalable enough to accommodate any potential changes in load, performance requirements, and new features.
These properties are essential if you want your application to live for a long time, maximizing your ROI.
To achieve this, do what you can to ensure that the new design does not burden the system with unnecessary constraints.
5.4 Industry Best Practices
Most clients automatically assume that the vendor follows industry best practices for design, development, and testing. Unfortunately, this is not always true.
Give the reader some information on the internal development processes you intend to follow. Mention essential steps such as code review and test plan preparations.
Finally, let the client know how to reach you for support and how you typically address quality issues. This will make the support process clear and efficient.
5.5 Security and Compliance
Heavily regulated industries such as insurance, health, and payments need to remain on top of their regulatory requirements. It is possible to have compliance updates so huge as to warrant their own project.
If you work in similar industries, be sure to include any security and compliance details in your analysis and design.
5.6 Backward Compatibility and Regression Issues
Imagine that your credit card suddenly stops working because it is not supported on the latest software version, which was deployed yesterday!
To avoid any drama during production rollout, perform a detailed analysis of the impact on downstream systems. More crucially, look for any potential backward compatibly problems.
Once you have done that, you can use the results to limit the scope of your testing while maintaining good coverage.
Mission-critical systems typically require an uptime of 99.5% and above. Businesses allow these systems to go down for scheduled maintenance and upgrades, and this means that any design fault can become a significant pain during go-live.
6. What Does a Good Solution Design Document Look Like?
We already talked about the contents of the design document. Now it’s time to say a few words about style.
The idea is to follow industry best practices and guidelines for technical documentation. In this section, we present five pillars that can guide you through the writing process.
6.1 Identify Your Audience
6.1.1 What It Means
Identifying the audience of any technical document is the most significant step in the writing process as it will drive the contents of the document.
In the context of software development, the audience might include business analysts, technical staff such as developers, testers, DevOps engineers, and project managers.
Excellent technical documentation addresses each audience segment in a language they understand.
Find out what the audience is expecting from this document. Make sure there is a section in the beginning that anybody can read. Call it Overview or Executive Summary.
This introductory section will help the reader determine whether or not this document is helpful for them.
6.1.2 How To Do It
Include the following sections in the document:
- Start with an Overview section that helps the reader decide if this document is useful for them
- Glossary of terms and acronyms: highly useful when the audience is new or has a mixed set of skills
- Appendices: this section shields the general reader from uninteresting details that might not be directly relevant to them
- Table of References for documents that have been referenced while preparing the solution design. This is probably much more important than it sounds as it creates a baseline on which the current design is built. Moreover, this will help trigger the proper change management process in case the specs get modified.
6.2 Outline the Project Scope
6.2.1 What it means
The LLD should be a one-stop-shop for the solution design. It needs to cover the system front-to-end.
But more importantly, the low-level solution design specifies which changes are in scope, and which are not.
Unclear requirements are the #1 cause of IT project failures. Make sure you have clearly outlined what’s in scope and what’s not. Only revisit scoping when absolutely necessary to prevent scope creep.
Requirements in the BRD should have a one-to-one mapping with sections in the LLD. This way, you guarantee that all requirements are covered.
An LLD should clearly delineate the boundaries of what’s in scope and what’s not.
A good LLD will detail the impact on the whole ecosystem allowing project managers from both sides to have a holistic and full view of the landscape paving the way for everybody to buy-in.
6.2.2 How To Do It
- Create a one-to-one mapping between the design and requirements in the BRD
- Create mock-ups for new screens
- Include an out-of-scope section. This is one way of avoiding free work!
- Perform full impact analysis and include all the possible implications
- Explicitly mention all the technical decisions that were made during the system design
6.3 Provide Enough Clarity
6.3.1 What it means
Software is a complex business and the LDD should try to untangle as much of that complexity as possible.
6.3.2 How To Do It
Use the below questions to determine whether the LDD is adequately clear.
- What are the assumptions that have been made during the design?
- What are the critical decisions taken, and how were the conclusions reached?
- Has the design placed any constraints on the future evolution of the product?
- Is there enough information (text, visualizations, tables, diagrams, process flows) to help assimilate the more complex ideas?
- What are the prerequisites for each task?
- Are there any open questions left?
- What is expected from the different stakeholders (internal and external)?
- Will the proposed changes present any foreseeable integration issues within the ecosystem?
- Will other functionality (features, data, reports, user experience) be impacted or modified by the change?
- How will other teams (such as support and operations) be impacted?
- Can the project be smoothly carried out if the designer is on vacation for a couple of weeks?
- Have the risks on the budget, timeline, service availability, and customer experience correctly tabulated and mitigations elaborated?
6.4 Be Precise
6.4.1 What It Means
Precision is its own reward.
Technical documentation should not contain ambiguous statements that can be interpreted differently.
Being precise in your words shows the reader that you are fluent in the topic. It also serves to build that level of confidence required for successful projects.
Also, being accurate is not enough; you need to be precise.
This can only lead to deferring design decisions to the development phase and having to design on the fly.
Accuracy vs Precision
To illustrate the point, consider the statement “The age of a man is between 0 and 200 years”. It is fairly accurate but not very precise. A much more useful expression would be: “The age of that man is 70 + or – 5 years”.
6.4.2 How To Do It
Here are three steps that will make your documents clearer:
- Use concise terminology, always!
- Avoid using words that lack preciseness such as probably, maybe, and it seems that.
- Do not leave any questions open-ended.
By having a definite position on every question, there will be no escape routes when things go wrong. This strategy ensures commitment from everyone.
The best way to evaluate clarity and completeness is by getting early feedback from collaborators and stakeholders. This can be achieved by setting up sessions where the design can be “challenged” and alternative pathways explored.
6.5 Comprehensive But Not Tedious
6.5.1 What It Means
The solution design document should provide enough detail so that you don’t have to go looking at other documents.
Having said that, it should not try to replicate information that can be obtained easily from other sources. Also, it should not aim at replacing the functional specs of any of the constituent products.
6.5.2 How To Do It
A good test for comprehensiveness can be as follows: if the author decides to leave on a two-week vacation, can work resume smoothly and efficiently for the entire period of her absence?
As with any piece of technical documentation, the quantity and relevance of the presented information ultimately decide its usefulness and accessibility.
6.6 Make It An Easy Read
6.6.1 What It Means
Create a document that is easy to read by the intended audience. Readability tests (Flesch-Kincaid) measure how easy or difficult a passage is.
If technical writing is your thing, read on how these tests assess readability and see if there is anything you can improve.
6.6.2 How To Do It
The following list should help your reader run smoothly through the document.
- Structured paragraphs and short sentences help the reader quickly go through the document.
- Avoid typos, sentence fragments, and grammar mistakes.
- Use simple terms without dumbing down the content.
- Add as many visualizations as required to help the reader digest the content.
- Enter all external references in a table at the beginning of the document.
- Provide a glossary for acronyms.
7. Solution Design Document Template
Use the below topics as a skeleton for your solution design document template:
- Overview or Introduction:
- It can be easily read and understood by anyone.
- Allows the reader to determine whether this document is helpful/accessible for them.
- Summary of Existing Functionality:
- Provides some context and background while linking new requirements to existing ones through external references.
- Requirement Details:
- A breakdown of the business requirements with comments and discussions.
- High-level requirements should map to the BRD. Low-level requirements should map to component specifications.
- It helps determine which requirements are already met, excluded, or require further clarification.
- 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.
- 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.
- Not to be confused with the High-Level Design Document (HLD) which contains overlapping but a lot more information on the solution.
- Low-Level Design:
- Details the low-level requirements of the subcomponents and submodules.
- 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.
- 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.
- Essential for a mutual understanding of what will not be covered in the current project.
- It helps lock in the scope and avoid any potential scope creep.
- 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.
- Additional information that could be too detailed or not strictly relevant to the topics discussed
- It can be presented for completeness and clarity.
Try to avoid the temptation of diving into development or implementation straight after the sale is closed. This action is a common mistake that puts your project at unnecessary risk.
Unless your project is tiny, there is no excuse for proceeding without any design if you want to achieve Operational Excellence in your work.
You will need to decide how much documentation, design, and analysis efforts are enough. Draw a line below which you do not go, regardless of the project’s size or proximity of deadlines.
If your processes today are messy, invest some time to improve them. Make sure you have templates ready, knowledge shared and propagated between teams, and your people are clear on what the development lifecycle consists of.
Avoid cheap and empty slogans like “we don’t have time”. Root out the problems that prevent you from finding the time to generate quality work.