Part 4: Solution Design Documents — What You Need to Know

Georges Lteif
Georges Lteif
Software Engineer

Last Updated on January 19, 2023.
Subscribe now to stay posted!
About Us
17 min read


1. Overview

Need to write a Solution Design Document (also known as Low-Level Design or LLD) for your upcoming assignment? You have come to the right place!

If this is the first time you have worked on such a task, we recommend you go through Part 1 of this series, where we introduce the basic concepts behind IT solution design.

Engineers, tech leads, and architects spend a lot of effort thinking about how best to design an IT solution.
Engineers, tech leads, and architects spend a lot of effort thinking about how best to design an IT solution.

The design phase is an integral part of the Software Development Lifecycle (or SDLC), producing quality artefacts without which subsequent steps (in this case, development and testing) will suffer.

Heavy design and documentation are only for some projects, however. Agile and other lightweight methodologies generally steer away from extensive and extreme design, planning, and documentation.

But Agile has a bounded domain of applicability, as we have endeavoured to show in separate articles. Part 1 walks you through the criteria to help assess your situation.

This article will examine the following topics:

  1. Top reasons why you need a Low-Level Solution Design
  2.  What does a Solution Design Document contain?
  3.  Tips on writing excellent technical documentation
  4.  A handy and straightforward Solution Design Document template

Related —


2. Designing IT Solutions — How Does It Work?

2.1 Complex Solutions and Agile Design

There are two extreme types of IT projects and a continuous spectrum of different shades between them.

On one extreme, we have standard technology, articulated needs, detailed business requirements, mature compliance regulations, and reliable predictions of cost, schedule, and future benefits.

On the opposing end of the spectrum, the scene is dominated by unarticulated needs, novel technology, minimal standards or regulatory requirements, and high uncertainty on future project benefits, costs, and timeframes.

An IT solution in the first scenario may be designed with a top-down approach, and while it might not be elementary, it will not show signs of complexity.

Under such conditions, a detailed solution design document, as this article describes, and a Waterfall project delivery methodology will work very well.

In contrast, designing a comprehensive answer at the onset of a project is very challenging if you are unsure how user preferences will change (as they will surely do) when they start interacting with the product.

Here, we must use an Agile design, the topic of a separate article.

Related —

2.2 Context and Background

We concluded Part 1 of this series by choosing four categories through which all IT projects must fall according to two criteria: scale and uncertainty.

Deploying the right tools and methods requires correctly identifying the category in which a project falls. The two variables used for this categorisation are scale and uncertainty.
Deploying the right tools and methods requires correctly identifying the category in which a project falls. The two variables used for this categorisation are scale and uncertainty.

The efforts we deployed in Part 2 culminated in a rigorous study of large system integration projects with large scale and low uncertainty since most platforms participating in the solution are considered mature.

In contrast, Part 3 focused on Agile design for projects with high customer interactions during requirements definition and mainly characterised by unassailable uncertainty. These projects are smaller in size and are, therefore, manageable.

In our present discussion, which will be the fourth instalment of the design series, we examine the topic of Low-Level Design Documents, also known as Solution Design Documents or simply LLD.

Part 5 is concerned with High-Level Design (HLD) and, in the SDLC order, comes before the LLD.

To cover four categories, we discussed mega-projects in a separate article.

Related —

2.3 Architecture and Design

While many definitions of architecture and design happily coexist in software dictionaries, with some experts using both terms interchangeably, we chose a different path based on knowledge gleaned from NASA’s Systems Engineering handbook.

Architecture involves the creation of multiple concepts and the selection of a suitable candidate that satisfies project and technical constraints.

In contrast, a design optimises solution parameters to provide excellent business value (functional and non-functional business requirements) at the lowest cost (implementation, maintenance, and operation).

It is crucial to distinguish architecture from design, especially when selecting the topics to tackle in a Solution Design Document.

While architectural plans are treated in the High-Level Design, an LLD focuses on the low-level technical decisions (data model, design patterns, code areas impacted), implementation (algorithms, pseudo-code), and their impact (validation and testing).

Related —

2.4 Product vs Solution

People sometimes use the words product and solution interchangeably, but that is not very accurate. See product vs solution for a complete discussion and comparative analysis.

A solution design consists of multiple products, platforms, or third-party systems or services, integrated to offer an end-to-end customer solution.
A solution design consists of multiple products, platforms, or third-party systems or services, integrated to offer an end-to-end customer solution.

A product is a tool or service that delivers a specific functionality of interest to the client. On the other hand, a solution is expected to solve the customer’s business needs by integrating more than one product into a functioning whole.

Products interact via interfaces with other products, end users, or the environment in which the solution operates.

A Solution Design Document must cover the entire solution end-to-end, avoiding a narrow focus on a subset of products.


3. Solution Design Document (SD, LLD)

3.1 Definition

A solution design document (LLD, SD) has five reasons to exist.
A solution design document (SD, LLD) has five reasons to exist.

Below is our definition of a Solution Design Document:

  1. It is a technical document produced during the design phase of the Software Development Lifecycle.
  2. It is created by a solution architect and reviewed by technical stakeholders, including developers and business analysts.
  3. Its 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 any technical decisions that change a product’s features.
  4. It aims to provide stakeholders with enough clarity on how their business requirements will be met.
  5. The Solution Design Document has enough details to allow a precise effort estimation to occur and the drafting of a detailed project plan.

Related —

3.2 Contents

A solution design document covers functional and non-functional requirements, third-party software, hardware, configuration, and data.
A solution design document covers functional and non-functional requirements, third-party software, hardware, configuration, and data.

A solution design document covers the following topics:

  • Technical design supporting non-functional requirements — Similar to the above, this section describes all hardware and software changes that support non-functional requirements. The latter might not be articulated or documented enough, but a close collaboration between the architect and senior developers will identify the required changes.
  1. Third-party software — This section covers all third-party software, libraries, frameworks, interfaces, licenses, and APIs provided through external vendors that might need testing or integration effort.
  1. Hardware — This section lists all hardware or hardware-related changes. It may include additional servers, network devices, licenses, cloud subscriptions or services, or specialized equipment.
  1. Configuration and data — Most applications have parameters that allow integrators to modify their features’ behaviour without changing the code. An excellent solution design document will also cover these modifications for tracking and testing purposes. In addition to configuration changes, data might be inserted, updated, or deleted from an application’s database, resulting in potential behavioural changes that need to pass quality assurance, and must, therefore, be documented.

3.3 Format

Despite their relatively young age, JIRA and Confluence (and similar applications) have come to dominate the stage to such an extent that we cannot imagine the world of IT without them.

Although expensive, these applications are critical knowledge capture and collaboration tools, allowing users to create rich content, internal and external page linking, customized fields, and more.

You can write code in notepad, but the money you save by not acquiring a decent commercial IDE will be more than compensated by the accumulated and compounded effect of delays and late deliveries.

Similarly, JIRA and Confluence are ideal examples of specialized precision tools (like advanced IDEs) indispensable for productivity work.

If you can secure their budget, use them to document your Solution Design or any other technical artefact.

3.4 Objectives

We would like our Solution Design Document to achieve the following objectives.

A detailed, well-documented design will allow stakeholders to voice concerns before buying in. It also allows project managers to create detailed schedules and effort estimations while understanding the dependencies.
A detailed, well-documented design will allow stakeholders to voice concerns before buying in. It also allows project managers to create detailed schedules and effort estimations while understanding the dependencies.
  1. End-to-End Design — Within an LLD, we would like a one-stop shop for our end-to-end design. Every major technical decision is documented with evidence supporting the chosen path.
  1. Stakeholder Buy-In — Implementations, especially if they are sizeable and transformational, may take time to materialize, require difficult decisions, and a constant renewal of commitment. For this reason, it’s good to have the stakeholders on your side, and the LLD can provide them with an opportunity to be intimately involved and afford enough clarity for them to buy in.
  1. Impact Analysis — The LLD describes the technical, operational, and functional changes that will be applied to the system. Ideally, we should see a one-to-one mapping with business requirements from the BRD. Comprehensive impact analysis allows developers, testers, DevOps engineers, and end users to prepare most effectively.
  1. Project Risk — Any decision made today, especially concerning architecture, might echo into the future. Every change applied today, especially in complex systems, carries a potential risk of service disruption and financial or reputational damage. Transparency and a coordinated strategy allow stakeholders to prepare for knowable eventualities and mitigate threats with various risk management techniques. The LLD strives to clarify any uncertainty and highlight project risk to the decision-makers.
  1. Project Scope — Scope creep is every project manager’s nightmare, as every new requirement has the potential to cause cost and schedule overruns. The solution design must endeavour to list all system changes expected to be delivered in this project and defend the project scope by providing project managers with enough information to allow the distinction between current and new change requests to be made.
  • Project Cost and Schedule — A thorough analysis of every change to be implemented allows project managers to produce a detailed plan with explicit dependencies and a comprehensive depth in tasks and subtasks. The project plan can then include a sufficient contingency to mitigate any risks, and the effort estimation will be more precise.

Related —

3.5 Benefits

Investing in designing and documenting IT solutions is one of many tools to help you achieve Operational Excellence in project delivery with a high cost of change.

The benefits of having a Solution Design Document (SD) far outweigh the cost of producing it in terms of reducing the risks of designing something that customers don't want or having to live with a poorly designed product for many years.
The benefits of having a Solution Design Document (SD) far outweigh the cost of producing it in terms of reducing the risks of designing something that customers don’t want or having to live with a poorly designed product for many years.

Failing to produce a solid design carries the below risks:

  • Unclear low-level business requirements, leading to poorly designed or even unusable software.
  • Sub-optimal design that cannot scale or perform reliably
  • Forcing developers to design on the fly, a risky adventure in highly complex systems where effective changes require technical expertise and business knowledge
  • Constant and frustrating rework as expensive and inefficient experimentation continues with developers trying to cope with complex changes and challenging coordination with other delivery units or departments
  • Insufficient or inappropriate software verification and validation due to poor impact analysis

Related —

3.6 Impact Analysis

Although we have briefly covered impact analysis, it is beneficial to articulate the topic and its relation to the LLD a bit more.

Testing, especially if it involves manual tasks, is a time-consuming, effort-intensive, and laborious anti-pattern that efficient project delivery seeks to minimize without compromising software quality.

Targeted testing is a good strategy in this situation, allowing testers to focus only on the impacted areas, thus reducing the overall testing effort without risking regression problems.

The targeted testing strategy requires precise knowledge of what has changed; this is where impact analysis can make a difference, and a bidirectional traceability matrix is an excellent tool for achieving precisely that.

Impact analysis is still effort intensive, although, with the bidirectional traceability matrix, you only need to prepare it once and update it with every project.

The traceability matrix is a 2D table with features on the vertical axis and code modules on the other. Looking at this table, you can quickly link a code change to a feature or vice versa.

To avoid performing creating and maintaining a traceability matrix, you must have fully automated testing to get full coverage on demand.

Of course, there are other ways to prepare test cases for a project, but they are not as efficient or effective.


4. What Drives a Solution Design?

4.1 Design as an Optimization Process

A properly-designed solution means building something where customers can find great utility and business value.

Business requirements can be challenging to understand and implement for reasons we discussed in detail in a separate article. As far as design is concerned, business requirements are constraints that a viable solution must satisfy.

Therefore, design is essentially an optimization process where architects find a technological solution that offers maximum value at the lowest cost and with regulatory, compliance, security, scalability and performance constraints (what we call non-functional requirements) satisfied.

The best and most familiar example of project constraints is time and money, and 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 disentangle their dependencies and mutual impact.

The diagram below shows the most common influential drivers that shape a solution design.

What drives a solution design?
What drives a solution design?

We review these requirements in the following paragraphs. We invite the reader to go through Part 2 of this series to complete the discussion.

Related —

4.2 Business Requirements

The default method for communicating requirements is the Business Requirements Document (or BRD). Alternatively, clients can use Epics and User Stories when practising Agile.

If a BRD is unavailable (this should never be the case!), the LLD needs to capture a mutually acceptable form of the client’s requirements in addition to design.

Requirements in the BRD must have a one-to-one mapping with changes in the described solution design.

Related —

4.3 Hardware and Infrastructure

Buying new hardware is always an event, requiring budgeting and many approvals as it increases the running costs of the existing infrastructure.

In addition, many departments, such as accounting, compliance, and procurement, must be involved in purchasing new hardware.

Also, hardware is not just servers! It can also be specialized equipment, network components, cabling, racks, licenses, support, administration, and extra space in the data centre.

Be sure to include a generous amount of detail on the hardware setup in your LLD. Also, cover all environments from development to QA and production.

4.4 Future Proofing

Future-proofing in technology is futile and can never be guaranteed long-term.

We can, however, do our best to ensure that what is implemented today is flexible, modular, and scalable enough to accommodate any short-term changes in user preferences, technology, and performance.

The solution design must remedy any unnecessary constraints on the product’s future development.

4.5 Industry Best Practices

Most clients automatically assume that the vendor follows the industry’s software development practices. Unfortunately, this is not always true.

The LLD can shed some light on the internal production processes you intend to follow, allowing stakeholders to participate in the development process, such as attending showcases or demos.

The Solution Design Document can also cover essential steps, such as code review and test plan preparations, for maximum involvement and commitment.

Finally, the LLD can let the client know how to reach you for support and how you typically address quality issues. This knowledge will make the support process straightforward and efficient.

Related —

4.6 Security and Compliance

Heavily regulated industries such as insurance, health, and finance must remain on top of their regulatory requirements.

It is possible to have substantial compliance updates warranting a dedicated project.

If you work in similar industries, include security and compliance-related changes in your analysis and design.

4.7 Backward Compatibility and Regression

To avoid any drama during production rollout, perform a detailed impact analysis on systems downstream.

More crucially, look for potential backward compatibility problems across interfaces or legacy software.

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.9% and above. Businesses rarely allow these systems to go down, even for scheduled maintenance and upgrades relying on secondary sites to bear the load during the downtime.

Any design fault causing deterioration or service interruption can become a significant pain after go-live.

Related —


5. Guidelines for Writing Technical Documentation

Let’s turn our attention now to format and style. This section presents five pillars that can help you create a fine technical document. Most of the below would apply to any technical documentation, not just the LLD.

Technical documents must have five attributes: clarity, proper scope (good coverage), accessibility, correct identification of the audience, and precision.
Technical documents must have five attributes: clarity, proper scope (good coverage), accessibility, correct identification of the audience, and precision.

5.1 Identify Your Audience

5.1.1 What It Means

Knowing your audience allows you to choose the depth and breadth of topics you want to tackle; in this case, your audience is the project’s technical stakeholders. These include business analysts, developers, testers, DevOps engineers, and project managers.

Your audience will also dictate the document’s style, technical jargon, and general tone. It is typical for technical specifications to be dry, but they must be straight to the point.

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. These introductory paragraphs will help the reader determine whether or not this document is helpful for them.

5.1.2 How To Do It

Include the following sections in the document:

  1. Overview — Start with this section to help the reader decide if this document is helpful for them.
  1. Glossary of terms and acronyms — highly useful when the audience is broad and might have limited knowledge of the subject. Natural language can also be notorious for ambiguity.
  1. Appendices — This section shields the general reader from uninteresting or highly-technical details that might not be directly relevant to their area.
  1. Table of References — This can become very handy for documents referenced while preparing the solution design, such as a Business Requirements Document (BRD) or the Interface Design Document (IDD). This table also shows the foundational knowledge on which the current design is built. Moreover, it will help trigger the proper change management process in case the specs get modified.

5.2 Outline the Project Scope

5.2.1 What It Means

Unclear requirements are the #1 cause of IT project failure.

The LLD should be a one-stop shop for solution design and must cover the system front-to-end, definitively locking the project scope.

Make sure you clearly outline what’s in scope and what’s not, preferably via a one-to-one mapping to features in the BRD and parallel entries in the project plan.

Only revisit the project scope when necessary (and involve the project manager) to prevent scope creep.

Equally important is to list items that are not in scope, especially where boundaries can be blurred or highly technical.

5.2.2 How To Do It

  1. Create a one-to-one mapping between features in the BRD, subtasks in the project plan, and design plans in the Solution Design Document.
  1. Create mock-ups for new screens, showing the intended changes. Use a standard modelling language to show the GUI changes and their functionality and type.
  1. Include an out-of-scope section. This is one way of avoiding free work, scope creep, and project failure!
  1. Perform a complete impact analysis and include all the consequential implications on features or downstream systems.
  1. Explain all the technical decisions made during the system design, with summary descriptions of the reasons that led you to make these specific technical choices

5.3 Provide Enough Clarity

5.3.1 What It Means

Can the project be smoothly carried out if the designer is on vacation for a couple of weeks?

Software is a complex business, and the LDD should try to untangle as much of that complexity as possible for all the reasons we detailed in the previous sections.

5.3.2 How To Do It

Use the below questions to determine if the LLD is missing any crucial information.

  1. What are the assumptions made during the design?
  1. What were the consequential technical choices, and how were the conclusions reached?
  1. Has the design placed any unnecessary constraints on the future evolution of the product?
  1. Is there enough information (text, visualizations, tables, diagrams, process flows, use cases) to reduce complexity and cognitive load on the reader?
  1. What are the prerequisites for each change? What is expected from the stakeholders (internal and external, such as vendors, suppliers, and other departments)?
  1. Are there any open questions left?
  1. Will the updated design present any foreseeable system integration issues within the ecosystem?
  1. Is there any impact as a result of feature or system coupling?
  1. Which stakeholders (operations, customers, sales, engineering, maintenance) are impacted, and are they all notified?
  1. Has project risk been adequately assessed, and have mitigation plans been implemented?

5.4 Precision

5.4.1 What It Means

Technical documentation should not contain ambiguous statements that can be open to interpretation.


Precision is its own reward.
Anonymous

Articulating complex ideas shows the reader that you are fluent in the topic and builds the confidence required to conclude a project, including making difficult technical decisions with long-term consequences.

Also, being accurate is not enough; you need to be precise. 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 helpful expression would be: “The age of that man is 70 + or – 5 years”.

This can only lead to deferring design decisions to the development phase and having to design on the fly.

5.4.2 How To Do It

Here are three steps that will make your documents clearer:

  1. Use concise terminology, always! Consistency is key, especially when semantics are not context-free.
  2. Avoid using phrases that convey doubt, such as probably, maybe, and it seems that.
  3. Leave no open questions.

Having a definite position on every question makes accountability clear.

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.

5.5 Comprehensive But Not Tedious

5.5.1 What It Means

The solution design document should provide enough detail so that you don’t have to look at other materials as far as the design is concerned.

At the same time, it must not tackle topics it doesn’t own or duplicate information more sufficiently defined elsewhere.

Judicious application of these two concepts keeps the documentation effort, an activity that does not generate any business value, to a minimum.

5.5.2 How To Do It

  • Topics unrelated to design should be tackled elsewhere. This restriction can apply to interface specifications (IDD), testing strategies, or operational guidelines.
  • The reader should be able to jump to a section or paragraph and glean the relevant information without having to go through the entire document for context.
  • A reference table links relevant material that can be consulted if required.
  • Appendices can provide technical details or information not necessary to understand the main story.

5.6 Make It Easy to Read

5.6.1 What It Means

Accessibility improves usefulness and value and is determined by the words you choose, sentence structures, and rich content.

Create a document that is easy to read by the intended audience. Readability tests (Flesch-Kincaid) can help you assess the difficulty of your scripts.

5.6.2 How To Do It

  • Structured paragraphs and short sentences help the reader quickly go through the document.
  • Avoid typos, sentence fragments, and grammar mistakes. Text editors’ embedded tools can easily help you get around this issue.
  • Use simple terms without compromising the content.
  • Add as many visualizations and rich content as required to help the reader reduce complexity and ease the cognitive load.
  • Provide a glossary for acronyms.

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

7. Final Words

It might be very tempting to dive straight into development without any design, relying on the developer’s expertise to cover the gaps. Business stakeholders might even endorse such thoughts based on budgetary or schedule constraints, putting the initiative at unnecessary risk.

Lack of design is an undeniable factor in project failure. Having to mention this fact explicitly, even today can sound strange, but the cost and time pressures can be enormous and technical stakeholders must learn to push back.

This risk is amplified for large system integration projects where requirements are generally precise, and top-down design and Waterfall are perfectly acceptable.

Investing in design gets everybody on board, allows all stakeholders to contribute (and commit), and prevents the project from proceeding on assumptions instead of facts.

Unless your project is tiny, there is little excuse for excluding design, mainly if you value Operational Excellence and a higher value proposition.

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.


Leave a Reply