System Specifications vs. Requirements

In the previous chapter, we introduced the System Specification document, which serves as an input for development, describes system capabilities, and instructs developers on implementation details like architecture and design. But how does this document compare to common formats like a Software Requirements Specification (SRS) or a Software Design Description (SDD)? Is a single System Specification sufficient, or do we need multiple documents? And which information belongs where?

The confusion stems from the fact that there is no sharp dividing line between requirements and designs. From an analyst’s perspective, if something must be implemented because stakeholders requested it, it is a requirement; otherwise, it is a design choice. However, the 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 hard separation, and labeling something a requirement or a design always depends on context.

For example, suppose stakeholders need a new screen to display a list of suspicious persons. This list is provided by an external company via a CSV file that can be downloaded from their website, where it updates every night at 2 AM. The core requirement is to display the most recent list of suspicious persons provided by that company on the screen. Because technical details—such as exactly when and how the data is downloaded—are not important to stakeholders, they are not part of the contract with them. In other words, they are designs.

However, this situation can look different depending on the audience. Let’s say an enterprise architect on the customer side tells a vendor that while there are two ways to get the data (real-time or batch), company policy mandates using a batch interface. This is a technical detail that does not matter to end-users who just want to see data on a screen, but it now becomes part of the contract with the customer. From the end-user’s perspective, it is an implementation detail, but from the vendor’s perspective, it is an important requirement that significantly influences system design.
Clearly, strictly separating requirements from designs is an impractical approach; in many cases, they are two sides of the same coin and must be elaborated together.

Requirements Document and Design Document?

The real discussion is not about how many documents to create or what to name them, but how to structure the information needed to build the solution. The sole goal is to provide a solution description in a form that enables stakeholders to verify what will be delivered, helps developers understand what they need to build, and does both efficiently while keeping documentation to a minimum.

First, both stakeholders and developers must 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 must be created, stating why it is needed. This can live either in the Solution Description or directly in the System Specification if the change is small. If both documents are created, duplication should be minimized as much as possible.

The next step is specifying the solution in detail. In most cases, it is helpful to divide this activity into two steps: first, capturing what needs to be built from a stakeholder perspective, and second, supplementing it with the technical implementation details required by the development team. Exactly how you separate these two layers is less important than ensuring you can verify system capabilities with stakeholders without distracting them with technical minutiae.

Experience shows that creating two entirely separate artifacts—one for stakeholders and one for developers—is rarely practical, mainly for the following reasons:

1. As stated, it is impossible to strictly separate requirements from designs because describing a system completely independent of technology is rarely feasible. It is more natural to keep them together coherently.
2. Designs are often just an evolution of high-level user requirements; it is simply another layer of detail. Separating them leads to unnecessary duplication.
   • For example, capturing use cases in one document and their technical realizations in another requires manual synchronization every time a change occurs. Even if documents are generated automatically, the process remains prone to errors.
3. Customers rarely want to read a formal list of isolated requirements; they want to understand how the system will work.
   • Stakeholders are generally not fans of reading dry specifications. It is the analyst’s responsibility to demonstrate functionality and explain system behavior. The goal is to structure documentation to allow top-down navigation, moving from general facts to detailed requirements and technical designs. This makes it easy to present the solution to stakeholders, starting with high-level concepts and stopping before the details become too technical for them. At the same time, developers can easily gather context from the exact same document and drill down to the technical details they need for implementation.

To sum up, unless explicit constraints dictate otherwise, keep your project information as coherent and integrated as possible. Even though developers implement technical realizations rather than abstract use cases, they still need the context of what they are building. It is then up to your documentation tools to easily filter or export two versions of the material—one with implementation details and one without.