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

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 your first time working on such a task, we recommend you go through Part 1 of this series, where we introduce the basic concepts behind IT solution design. 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 avoid extensive and extreme design, planning, and documentation.

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

2. What Does the Solution Design Series Cover?

This article belongs to a series that discusses solution design and will cover the topics below:

3. Designing IT Solutions — How Does It Work?

3.1 Complex Solutions and Agile Design

Two extreme types of IT projects exist, and a continuous spectrum of 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 (low uncertainty, low customer interaction, major integration projects…) may be designed with a top-down approach. 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, which is the topic of a separate article.

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

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.

3.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).

3.4 Product vs Solution

People sometimes interchange the words product and solution, but that is inaccurate. See product vs solution for a complete discussion and comparative analysis.

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.

4. Solution Design Document (SD, LLD)

4.1 Definition

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.

4.2 Contents

The following infographic shows five topics a typical solution design document must tackle.

A solution design document covers the following topics:

4.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 IT world 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 for 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.

4.4 Objectives

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

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

Failing to produce a solid design carries the following risks:

1. Unclear low-level business requirements, leading to poorly designed or even unusable software.
2. Sub-optimal design that cannot scale or perform reliably
3. Forcing developers to design on the fly, a risky adventure in highly complex systems where effective changes require technical expertise and business knowledge
4. 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
5. Insufficient or inappropriate software verification and validation due to poor impact analysis

4.6 Impact Analysis

Although we have briefly covered impact analysis, it is beneficial to articulate the topic and its relation to the LLD 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. This table lets you quickly link a code change to a feature or vice versa.

To avoid 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.

5. What Drives a Solution Design?

5.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 examples of project constraints are 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.

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

5.2 Business Requirements

The Business Requirements Document (or BRD) is the default method for communicating requirements. 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.

5.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, it covers all environments from development to QA and production.

5.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 unnecessary constraints on the product’s future development.

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

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

5.7 Backward Compatibility and Regression

To avoid any drama during production rollout, perform a detailed impact analysis on systems downstream. 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 going live.

6. Guidelines for Writing Technical Documentation

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

6.1 Identify Your Audience

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

6.1.2 How To Do It

Include the following sections in the document:

6.2 Outline the Project Scope

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

6.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.
2. Create mock-ups for new screens, showing the intended changes. Use standard modelling language to show the GUI changes, functionality, and type.
3. Include an out-of-scope section. This is one way of avoiding free work, scope creep, and project failure!
4. Perform a complete impact analysis, including all the consequential implications on features or downstream systems.
5. 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.

6.3 Provide Enough Clarity

6.3.1 What It Means

Can the project be smoothly carried out if the designer is on vacation for a few 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.

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

6.4 Precision

6.4.1 What It Means

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

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 designing on the fly.

6.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 to challenge the design and explore alternative pathways.

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

6.5.2 How To Do It

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

6.6 Make It Easy to Read

6.6.1 What It Means

Accessibility improves usefulness and value and is determined by your chosen words, 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.

6.6.2 How To Do It

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

7. Solution Design Document Template

Use the below topics as a skeleton for your solution design document template:

1. 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.
2. Summary of Existing Functionality:
   • Provides context and background while linking new requirements to existing ones through external references.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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.
9. 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.
10. Appendices:
    • Additional information that could be too detailed or not strictly relevant to the topics discussed
    • It can be presented for completeness and clarity.

8. 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 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 must 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.