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.
Design of Modern IT Systems Design process of modern IT systems and large software integration projects.
Agile Design Agile Design: Solution design under conditions of uncertainty. Solution Design Documents Generating detailed solution design documents (SDD). High-Level Solution Design Documents (HLD) How to create a high-level system design document or HLD. Component-Based Software Engineering (CBSE) A discussion of CBSE and its development process.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.
Part 3: Agile Design Techniques for Creating Strong and Scalable SolutionsWe 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.
What Can We Learn Today From Mega-Project ManagementWhile 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).
From Abstract Concepts to Tangible Value: Solution Architecture in Modern IT SystemsPeople 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.
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.
We would like our Solution Design Document to achieve the following objectives.
This point of view has produced the observation that there’s never enough time to do something right, but there’s always enough time to do it over. — Melvin Conway, How Do Committees Invent
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.
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.
Test and Automation Strategy: A Deep-Dive Into an Essential Solution for Your Daily Agile PracticesA 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.
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.
Business Requirements: An Essential Guide to Definition and Application in IT ProjectsBuying 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.
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.
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.
Principles of Operational Excellence in Software DevelopmentHeavily 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.
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.
Interface Design and Definition Document Template — A Short Guide for the Best ResultsLet’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.
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.
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.
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.
Use the below questions to determine if the LLD is missing any crucial information.
Technical documentation should not contain ambiguous statements that can be open to interpretation.
“Precision is its own reward”
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.
Here are three steps that will make your documents clearer:
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.
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.
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.
Use the below topics as a skeleton for your solution design document template:
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.
