System Specification

A system specification (or functional specification) is an artifact designed to provide all the information required to deliver a software solution or its components. While its purpose is clear, its exact content and structure are less obvious. There are dozens of types of IT systems serving different purposes, which implies that describing each one requires different techniques. Consequently, it is impossible to prescribe a single structure for every functional specification. Showing a simple warning message to customers versus describing an organization's core transactional system will obviously lead to completely different types of documentation. Similarly, an interface change will look different from a modification to a process-oriented workflow engine. The form and structure of a system specification must be tailored to the needs of each specific change.

One principle should remain common across all specifications, however: there must be a central element that glues the different parts together, connecting relevant information in a coherent way. For example, if a system is specified using use cases, the use case becomes the central element, holding together related elements like screens, backend services, or business rules. These elements link back to the use case to detail it further. Another example is a process-oriented system, where the central element is a process step that brings together aspects like the system where the step occurs, the screens used, and any services called. These questions should all be easily answered just by looking at the elements linked to that process step.

Furthermore, some systems are not operated by users directly and do not implement traditional use cases or processes. Typically, these are backend systems that provide services to other applications, run scheduled batch jobs, or purely store and analyze data. What is the central element here? It is not a use case or a process, but a central anchor still exists: it could be the services the system exposes, the events it responds to, or the data structures it stores.

In addition to the central elements forming the backbone of the description, every system is defined by technical aspects such as security, performance, or usability. Together with implementation constraints, dependencies, and assumptions, they form the essential parts of a system specification.

System Specification Approaches

Business requirements and high-level solution descriptions are best handled via a document format accompanied by a few diagrams or sketches to illustrate core concepts. A system specification, on the other hand, is a technical artifact requiring a broader set of tools. Some teams use traditional text documents, embedding models, wireframes, or spreadsheets, and store them on a shared drive or SharePoint. Other teams use sophisticated CASE tools that store all information in a database and automatically generate final documents from it. Each approach has distinct advantages and disadvantages, which are detailed in Part III. That section also introduces the "hybrid" approach favored by Effective Analysis.

Antipatterns

Here we present several antipatterns to avoid when creating system specifications.

1. Duplication

A lot of information in a functional specification originates in the business analysis phase, such as the product vision, high-level descriptions, or user classes. This information can change during development, and it is best to keep it in a single location rather than duplicating it across multiple artifacts. The recommended approach is to reference the information if it already exists elsewhere; it is quite common for the introductory sections of a system specification to simply link back to the BRD or Solution Description.

2. Listing Artifacts Outside of Context

We often see specifications containing isolated sections titled "State Diagrams," "Screens," or "System Services." While not strictly incorrect, what is the goal? Do authors expect readers to simply scroll through a standalone list of every screen in the system? Probably not. A screen makes sense only when presented in the context of a use case, process, or feature that it specifies. If an exhaustive list of entities is truly required, it should be automatically generated from a repository to prevent duplication and save time on manual updates. A list of services exposed by the system is a good example of something that should be handled this way.