Why is it important to ensure that the document design is consistent with the company and or client requirements?

Skip to content

Software Engineer

Last Updated on October 24, 2022.
Subscribe now to stay posted!
About Us
17 min read

This article focuses on documenting a detailed design, see Solution Design for concepts and definitions.

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.

If this is your first time creating a Solution Design document, or perhaps you are not entirely sure what Solution Design involves, we recommend you go through this article first.

It will provide some context and lay the groundwork for the present article. It will also explain why designing a solution before implementation is vital for the success of any project.

This article focuses primarily on 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.

Solution architecture and solution (or system) design are two overlapping but essentially different processes implemented at different stages of the project lifecycle.

We recommend that the reader familiarize themselves with both concepts before proceeding by following the links.

Heavy design and documentation are not for every project, however. Agile and other lightweight methodologies generally steer away from extensive and extreme design, planning, and documentation.

Depending on the nature of your IT project and the delivery method you adopt (Agile, DevOps, Waterfall), you might find investing in Solution Design documents a vital piece of your delivery process.

In the coming sections, we look at:

1. The purpose of having a documented LLD
2. What does a Solution Design Document involve
3. Tips on writing excellent technical documentation
4. A handy and straightforward Solution Design Document template

2. Table of Contents

3. What Is a Solution Design Document (LLD)

3.1 Definition

Let’s review a few key concepts defining a Solution Design document.

These concepts are as follows:

1. An LLD is a clear and concise technical document
2. Created by a solution architect during the design phase of the SDLC
3. That documents an end-to-end design for a software solution
4. 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:

1. Software: includes detailed low-level feature requirements and implementation details such as specifications, algorithms, process flows, diagrams, tables, code changes, or pseudo-code.

1. 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.

1. 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:

1. A detailed list of business features (should map into a business requirements document or BRD) or any other work to be done
2. Architecture and design considerations
3. Solution implementation details and any technical decisions made
4. Impact analysis of the updates or new features.
5. Software testing requirements such as updates required on automation tools or test scripts, and
6. Finally, any project technical risks 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. You can follow the link if you want the full details.

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

4.1 Objectives

The following list summarizes the aim of having a Solution Design document:

1. Document all the essential components of your software solution and their specifications and design parameters. These could be hardware, software, or application.

1. Describe the significant technical changes applied to your system or application. Any change that might impact how the system functions or operates must be explained appropriately.

1. 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.

1. Detail the large to medium-sized implementation changes to help developers, testers, and DevOps engineers perform their jobs without constantly looking for clarifications.

1. List what’s in-scope and what is out of scope to lock the scope and prevent scope creep.

1. 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 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 designing and documenting 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:

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.

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.

You need your stakeholders to buy in for active ownership and maximum collaboration. And to do that, they must be assured that the business requirements have been properly understood.

Include enough details for the development team to understand the expected source code changes. Use pseudo-code if required.

When changes are properly documented, 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 we highly recommend.

This step is crucial in eliminating any avoidable future rework due to poor design.

The dearest topic on the software tester’s heart 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 an 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.

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, 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

The default method for communicating business requirements is generally via a business requirements document (or BRD). Alternatively, clients can use Epics and User Stories when practising Agile.

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.

Buying new hardware is always a project because it usually requires budgeting and many approvals.

In addition, 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 design, development, and testing practices. Unfortunately, this is not always true.

Give the reader information on the internal production 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 must remain on top of their regulatory requirements. It is possible to have huge compliance updates warranting their own project.

If you work in similar industries, include 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 by the latest software version 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, which 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. This section presents 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 document’s style and depth and ensure that your stakeholders remain adequately informed.

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:

1. Start with an Overview section that helps the reader decide if this document is useful for them
2. Glossary of terms and acronyms: highly useful when the audience is new or has a mixed set of skills
3. Appendices: this section shields the general reader from uninteresting details that might not be directly relevant to them
4. Table of References for documents referenced while preparing the Solution Design, such as a business requirements document (BRD). 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 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 clearly outline 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

1. Create a one-to-one mapping between the design and requirements in the BRD
2. Create mock-ups for new screens
3. Include an out-of-scope section. This is one way of avoiding free work!
4. Perform full impact analysis and include all the possible implications
5. 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.

1. What are the assumptions that have been made during the design?
2. What are the critical decisions taken, and how were the conclusions reached?
3. Has the design placed any constraints on the future evolution of the product?
4. Is there enough information (text, visualizations, tables, diagrams, process flows) to help assimilate the more complex ideas?
5. What are the prerequisites for each task?
6. Are there any open questions left?
7. What is expected from the different stakeholders (internal and external)?
8. Will the proposed changes present any foreseeable integration issues within the ecosystem?
9. Will the change impact other functionality (features, data, reports, user experience) or modify it?
10. How will other teams (such as support and operations) be impacted?
11. Can the project be smoothly carried out if the designer is on vacation for a couple of weeks?
12. 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.

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:

1. Use concise terminology, always!
2. Avoid using words that lack preciseness, such as probably, maybe, and it seems that.
3. 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 look 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 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 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 much 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.
  • It can take the form of a bidirectional traceability matrix. The latter is extremely useful in linking business requirements to pieces of code and specific test cases, and user documentation.
• Out-of-scope: 
  • 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 third-party components’ availability in software modules, specifications, feedback, resource availability, etc.
  • Regression issues are introduced because of legacy code, poor documentation, or flawed software architecture or design.
  • 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.
• Appendices:
  • Additional information that could be too detailed or not strictly relevant to the topics discussed
  • It can be presented for completeness and clarity.

Solution-Design-Document-TemplateDownload

8. Conclusion

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.

Investing in design effort gets everybody on board, allows all stakeholders to voice their concerns, and prevents the project from proceeding on assumptions instead of facts.

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 clear on the development lifecycle.

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.

9. Featured Articles