Solution Design Documents: What You Need to Know

Georges Lteif

Georges Lteif

Software Engineer

Last Updated on July 19, 2021
About Us
15 min read

1. Overview

Need to write a Solution Design Document (SD or SDD) for your upcoming project?

In this article, we will try to equip the reader with a comprehensive set of ideas that will guide you through the process.

A couple of notes before we move on.

Not Sure What a Solution Design Is?

If you are not sure of what a solution design is and how it might help your IT projects, we have created a solution design guide that will tell you all you need to know.

What’s a High-Level Solution Design?

In this article, we talk mostly about the low-level solution design (LLD) and how to document it. If, instead, you are after a High-Level Solution Design, make sure to follow that link.

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

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:

  1. The purpose of having a documented SD
  2. What does it help you achieve
  3. Tips on writing great technical documentation
  4. A handy and simple Solution Design Document template

2. Table of Contents


3. What Is a Solution Design Document

Let’s go over a few key concepts that define a solution design document.

A Solution Design Document (SD or SDD):

  1. Is a clear and concise technical document
  2. Created by a solution architect during the design phase of the SDLC
  3. Documents an end-to-end software solution for a certain project
  4. Provides stakeholders with enough clarity on how their business requirements will be met.
solution design document template
Solution Design Document

The main themes that figure in the solution design document are usually:

  1. Software, i.e. licenses, code changes, pseudo-code…
  2. Hardware requirements
  3. Functional and non-functional requirements
  4. Project specific configuration data

What this means is that a solution design document will touch on a wide range of subtopics such as:

  1. Architecture and Design
  2. Impact Analysis
  3. Software Testing Requirements
  4. Scope
  5. Project Risks and Challenges

This means that the typical audience is formed mainly of technical people.

The list above is particularly valid for software development projects.

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:

Product vs Solution

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

4.1 What Is the Aim of a Solution Design

The aim of a solution design document is to document:

  1. All important aspects of your software solution
  2. Major technical changes to your software or solution
  3. Project risks and challenges
  4. Large / medium implementation details that would help developers and testers perform their job
  5. What’s in-scope and what is out-of-scope

The Value of Good Documentation

There is a 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 one assumption: achieving Operational Excellence in your software delivery requires you to identify those processes and their outcomes that generate business value. If you believe and can demonstrate the business value of solution design documents, then it needs to be part of your SDLC processes.

Investing time and effort in documenting a solution design is one tool of many that can help you achieve great results in projects where the cost-of-change is high.

4.2 Desired Outcomes of a Solution Design

Check the below image to see the expected outcomes from a solution design document. We will cover each of these in the next sections.

advantages outcomes objectives solution design document
Outcomes of a Solution Design Document

Let’s review these items one by one.

Stakeholder Buy-in

The primary objective of an SD 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 need to be assured that the business requirements have been properly understood.

Clarity on Changes

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

When changes are properly documented:

  1. The programmers avoid having to design on-the-fly
  2. Developers and testers are now able to make precise estimations of the efforts required
  3. Project managers can prepare detailed implementation plans. Remember, we are still at the design phase of the SDLC!
  4. Developers and testers have a solid foundation they can lean on to start writing their test cases. This is crucial when applying Test-Driven Development (TDD), a practice that we highly recommend.

This step is crucial in eliminating any avoidable future rework as a result of poor design.

Effort Estimation Tips and Tricks

Have trouble getting those effort estimations right? Software estimation can be complicated when factors such as employee skill levels are factored in. We have prepared this guide to assist you through the process.

By far the dearest topic on the tester’s heart: what is the scope of change and how much regression testing is expected.

Impact Analysis

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 especially to determine those features that have been impacted by the change and will need to be tested for regression problems.

The SD should answer those questions by performing an impact analysis on the anticipated code changes. A bidirectional traceability matrix is a great tool for achieving exactly that.

Evaluating Risk

Risk generally comes from project unknowns such as changing requirements or adverse side effects. Use the impact analysis to evaluate and mitigate any risk early on in the project.


5. Addressing Project Constraints

Designing a proper solution helps you deliver an application that the customer wants to use.

For the customer to accept the delivery and pay for it, the application needs to address their business needs.

These requirements can be viewed as multiple, many times conflicting, constraints. Designing a solution is essentially an optimization process.

Familiar Project Constraints

The best and most familiar examples of project constraints are time and money. In fact, the customer wants the best performance and greatest value to be delivered within a certain budget and timeframe.

A solution design document brings all these constraints together in one place and allows you to understand the mutual impact from one another.

Typical IT Project Constraints
Typical IT Project Constraints

The above diagram shows the major ones. In the coming sections, we will discuss each of these in detail.

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

The SD needs to capture, in addition to design details, a mutually acceptable form of client 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, procurement will be involved.

Hardware is Not Just Servers!

It can also be specialized equipment, network components, cabling, racks, licenses, support, administration, and especially extra space in the data center.

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

When it comes to future-proofing, we are really talking about scalability, extensibility, and modularity.

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 will not burden the system with unnecessary constraints.

5.4 Industry Best Practices

Most clients automatically assume that the vendor is following industry best practices for development and testing. Unfortunately, this is not always true.

Give the reader some information on the internal development processes you intend to follow. Mention important steps such as code review and test plan preparations. Let the client know how to reach you for support.

Finally, don’t forget to list the measures that will be taken to address any quality issues.

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.

5.6 Backward Compatibility and Regression Issues

Imagine that your credit card suddenly stops working because it is not supported on the latest version of the software 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 have a requirement for an uptime of 99.5% and above. Businesses allow these systems to go down only for scheduled maintenance and/or upgrades. What this means is any design fault can become a major pain during go-live.


6. What Does a Good Solution Design Document Look Like?

We already talked about the contents of the design document. Not it’s time to say a few words about style.

It is really just about following industry best practices and guidelines when it comes to technical documentation.

solution design document

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 influential step in the writing process. Because of that, it will drive the contents of the document.

In the context of software development, the audience might include business analysts, technical staff (developers, testers, etc.), and project managers.

Great technical documentation addresses each segment of the audience in their own language.

The “Overview” Section

Find out what the audience is expecting from this document. Make sure there is a section in the beginning that anybody could read.

This will help the reader determine whether or not this document is useful for him/her.

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 shields the general reader from uninteresting details that might not be directly relevant to them
  4. 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 SD should be a one-stop shop for the solution design. It needs to cover the system front-to-end.

But more importantly, the solution design specifies which changes are in scope, and which are not.

Unclear Requirements and Project Failures

Unclear requirements are the #1 cause for 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 SD. This way, you guarantee that all requirements are covered.

Project Scope

An SD should clearly delineate the boundaries of what’s in scope and what’s not.

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 a full impact analysis and include all the possible implications
  5. Explicitly mention all the decisions that were made during the system design

Providing a Holistic View

A good SD 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.3 Provide Enough Clarity

6.3.1 What it means

Software is a complex business and the SDD 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 SD has that level of clarity that you’re after.

  1. What are the assumptions that have been made during the design?
  2. What are the key 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 data (text, visualizations, etc.) 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. What other functionality (features, data, reports, user experience) will be impacted or modified by the change?
  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 properly tabulated and mitigations elaborated?

6.4 Be Precise

Precision is its own reward.
Anonymous

6.4.1 What It Means

Technical documentation should not contain ambiguous statements that can be interpreted in different ways.

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

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

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

6.4.2 How To Do It

Here are 3 steps that will make your documents clearer:

  1. Use concise terminology, always!
  2. Avoid using words like “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 to be used when things go wrong. This ensures commitment from everyone.

Evaluating a Solution Design

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?

Value of a Technical Document

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. There are readability tests (Flesch-Kincaid) that measure how easy or difficult a passage is.

If technical writing is your thing, have a 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 much 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:
    • Can be easily read and understood by anyone.
    • Allows the reader to determine whether this document is useful/accessible for him/her.
  • 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 new requirements with comments and discussions.
    • Helps determine which requirements are already met, can be excluded, or require further clarifications.
  • Assumptions and Prerequisites:
    • Is an integral part of the design process so that everybody is clear on the foundations on which the design was built.
    • This will also allow an early assessment of whether these assumptions are valid or acceptable or perhaps require a review.
  • High Level Design:
    • Through the usage of diagrams, tables, and other visualizations, this section aims to provide process flow updates and information pathway changes.
    • Typically also addresses integration issues with other systems.
  • Low-Level Design:
    • Can be achieved via flowcharts and pseudo-code
    • The aim is to pinpoint expected source code files and functions to be modified.
    • It will also give testers an idea of the scope of change and helps 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 on the market in terms of backward compatibility and any possible degradation or interruption of the service after the upgrade.
    • 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.
    • Helps avoid misunderstandings and potential “free work”.
  • 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 introduced as a result of work on legacy, poorly documented, or badly designed systems.
    • Incomplete requirements that require decisions to be deferred till 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
    • Can be presented for completeness and clarity.

8. Further Reading

  1. Draw.io is a powerful free tool for creating diagrams and flowcharts.
  2. A good explanation of Bidirectional Traceability Matrices.

Process Management, Improvement, and Redesign: The Essential Guide for Boosting Your Performance

1. Overview One of the earliest, if not the earliest, descriptions of continuous process improvement was laid out in Frederick W. Taylor’s book on Principles of Scientific Management (1911): In this short paragraph, we can observe a glimpse of several notions that will become seminal in later works on production and quality management like Six Sigma.Continue reading “Process Management, Improvement, and Redesign: The Essential Guide for Boosting Your Performance”

Organizational Culture, Transformation, and Change: FAQ

1. Overview In this article, we try to examine and answer the most common questions on organizational culture. The ideas and concepts are derived from Edgar Schein‘s seminal work which can be found in his 1990 paper or fantastic book on Orgazniational Culture and Leadership. 2. Organizational Culture FAQ 3. Featured Articles

Book Review: The Six Sigma Way: How GE, Motorola, and Other Top Companies are Honing Their Performance

Synopsis This work has been created by three authors: Peter S. Pande, Robert P. Neuman, Roland R. Cavanagh. There are two editions of this book. In this article, we will be reviewing its first edition which was published in 2000. This book offers an in-depth discussion of Six Sigma, an extensive framework for quality managementContinue reading “Book Review: The Six Sigma Way: How GE, Motorola, and Other Top Companies are Honing Their Performance”

Thoughts on Six Sigma for Developing Your Software Engineering Processes

1. Overview I have recently taken a lot of interest in the behavior of groups trying to achieve a common objective, especially those in professional environments. I wanted mainly to understand the differences between two arbitrary groups when it came to performance. Specifically, I was keen on knowing whether there was something that those groupsContinue reading “Thoughts on Six Sigma for Developing Your Software Engineering Processes”

Quantum Computing, Beyond Qubits – Part 3: AI, Optimization, and Quantum Annealing

1. Overview Perhaps a great way of starting this article would be by defining the high-level concepts behind combinatorial optimization and quantum annealing. Let’s tackle Combinatorial Optimization first. The best (or optimal) solution satisfies a certain condition such as the minimization (or maximization) of a cost function associated with this problem. We will have aContinue reading “Quantum Computing, Beyond Qubits – Part 3: AI, Optimization, and Quantum Annealing”

Book Review: Six Frames for Thinking About Information

Synopsis Eduard de Bono is perhaps most famously known for his ideas on Lateral Thinking and the decision-making framework better known as The Six Thinking Hats. He has published many original ideas in short, concise books such as this one, where he proposes a set of methods, or frameworks, for dealing with certain problems, problemsContinue reading “Book Review: Six Frames for Thinking About Information”

Loading…

Something went wrong. Please refresh the page and/or try again.

Leave a Reply