System Specification

System specification (or functional specification) represents a "document," which is meant to provide all information required to deliver a software solution or its components. While its aim is clear, what is not that obvious is its content and structure. There are dozens of types of IT systems serving different purposes, which implies that describing each system requires different techniques. As a result, it is not possible to prescribe what information the functional specification should contain and what structure it should have. Showing a warning to customers and describing the organization's core system will obviously lead to completely different types of the system specification. Similarly, describing a system interface change will look different than modifying a process-oriented workflow engine. The system specification form and structure need to be tailored to the needs of each particular change.
One thing should be common for every specification, though: there is always a central element that glues other parts of the specification together, coherently connecting relevant information. For example, if the system is specified using use cases, the use case becomes the central element of the specification, holding together other parts of the system such as screens, services or business rules. These elements are linked to the use case and specifying it in more detail. Another example might be a process-oriented system. In this case, the central part is a process step that puts together important aspects such as in which system the step is performed, what screens are used, whether the process step calls some system service, etc. These questions should all be easily answered just by looking at the elements linked to the process step.
Also, some systems are neither operated by users nor do they implement any use cases or processes. Typically, these are "backend" systems that only provide services to be consumed by other systems, perform scheduled long-running activities, or they only store and analyze data. What is the central element here? It is not a use case, it is not a process, but there is always one. It could be the services the system exposes to the outside world, it could be events which it responds to, or it could be data structures it stores. Besides the central elements forming the backbone of the system description, each system is also defined by the technical aspects such as security, performance, or usability. Together with the implementation constraints, dependencies and assumptions, they form the essential parts of the system specification.

System Specification Approaches

Business requirements and high-level solution descriptions are best described in the form of a document with a couple of pictures, diagrams, or sketches to illustrate the most important concepts. System specification, on the other hand, is a technical artifact, which requires a broader set of tools. Some teams use good old MS Word documents, put models, wireframes, or even MS Excel tables into them and store them on a shared drive or on a Sharepoint. Other teams use sophisticated CASE tools that store all information in the database and automatically generate the final documents from the database. Each approach has its advantages and disadvantages, which are elaborated in more detail in the Part III. This part also introduces the "hybrid" approach, which is favored by the Effective Analysis.

Antipatterns

Here we present several antipatterns that should be avoided when creating system specifications.

1. Duplications

A lot of information presented in the functional specification originates from the business analysis, such as the product vision, high-level description, user classes etc. This information can change even during the development of the software and it is better to keep it in one place and not to duplicate it in both artifacts. The recommended approach is to just reference the information if it is already present somewhere, so it is very common that the introductory parts of the system specifications are just links to the BRD or Solution description documents.

2. Listing Artifacts

Very often, we see specifications that include sections called "State diagrams", "Screens", or "System services". Even though it cannot be called "wrong", what is the goal? Do authors really expect somebody to go through the list of all screens in the system? Probably not. A screen itself makes sense only if it is presented in a context of a use case, process, or feature, which it specifies. If a list of entities is really needed, it must be automatically generated from a repository because otherwise, it presents duplication and possible waste of time on rework. For example, a list of services the system exposes.