System Specifications vs. Requirements

In the previous chapter, we introduced a System Specification document which serves as an input for the development, describes what capabilities the system shall have, and also instructs developers how it shall be implemented - the architecture and design. But how this document compares to the common formats such as Software Requirements Document (SRS) or Software Design Document (SDD)? Is the System Specification sufficient, or do we need multiple documents? And which information belongs to which document?

The whole confusion stems from the fact, there is no clear answer on what distinguishes requirements from designs. From the analyst’s perspective, if it is going to be implemented because stakeholders requested it, it is a requirement; otherwise, it is a design. However, analyst is not the only person in the development process, and what one person calls a requirement may be perceived as a design by another. There is no no hard separation and calling something requirement, or design always depends on the context.

For example, stakeholders need a new screen to display a list of suspicious persons. This list is provided by the ABC company via a CSV file that could be downloaded from the company’s website, where it is updated every night at 2 am. So the requirement is to display on the screen the most recent list of suspicious persons provided by the ABC company. Because the technical details such as when and how the data will be downloaded are not important for the stakeholders, they are not part of the contract with them. In other words, they are designs.

This situation may look differently, though. Let’s say there is an architect at the customer's side telling the vendor that there are two ways of getting the list, real-time and batch, but according to the company policy, it is required to use the batch interface. It is a technical detail that is not important for the users that just need to see the actual data on the screen, but now it becomes a part of the contract with the customer. From the end user’s perspective, it is a minor implementation detail, but from the vendor’s perspective, it is an important requirement that might significantly influence the design of the final system.
Obviously, strictly separating requirements and designs is a bad idea, as in many cases, they are just two sides of the same coin and need to be elaborated together.

Requirements Document and Design Document?

The whole discussion is not about how many documents should be created or how they should be named but how to structure information needed to develop the solution. The only goal is to provide solution description in a form that enables stakeholders to verify what will be delivered, from which developers will understand what they need to build and do both in the most efficient way, creating only the minimum documentation.

First, both stakeholders and developers should understand the purpose of the system and the value it is expected to deliver. This means a high-level description of the system or its modification should be created, stating why it is needed. This may be included either in the Solution Description or directly in the System Specification, in case it is just a small change. If both Solution Description and the System Specification is created, duplications should be avoided as much as possible.

The next step is specifying the solution in detail. In most cases, it is needed to divide this activity into two steps: the first step is capturing what is needed to be built from the stakeholders’ perspective and then complementing it with implementation details that are required by the development team. It is basically not important how these two layers are separated, the crucial thing is to be able to verify with the stakeholders what the solution will be capable of without being distracted by technical details.

Our experience shows that it is not convenient to create two artifacts, one for stakeholders and one for the development team, mainly for the following reasons:

1. As it was already stated, it is not possible to strictly separate requirements from designs as it is usually not feasible to describe the system completely independent of the technology. It is more natural to keep them coherently together.
2. Designs are very often just evolution of the high-level user requirements, it is just another view, which means that separating them would cause duplications
   • For example, capturing use cases in one document and their realizations in another requires synchronizing them every time either of them changes. Even if the documents are automatically generated, it is still prone to mistakes.
3. Customers usually do not require a formal list of requirements, they just need to know how the system will work
   • Stakeholders are not fans of reading specifications. It is the analyst’s responsibility to demonstrate the functionalities to them and explain how the system will work. The goal is to structure the documentation in a way that enables navigating top-down, from the general facts to more detailed requirements and technical designs. It is then possible to present the solution to stakeholders, starting with general things, and going deeper until the information is too detailed for them. At the same time, developers can easily learn the context from the very same document and seamlessly drill down to details they need for the implementation.

To sum it up, if nothing orders you otherwise, keep the information as coherent as possible. Even though the developers do not implement use cases but only their realizations, they are still interested in the context of what they are building. It is then up to the tools being used to easily prepare two versions of the documentation, one with the implementation details and one without it.