Effective Analysis and Documentation

System Specification Content

The following section presents the most common parts of the system specification, yet it does not represent a template prescribing what the specification should include. It is rather a set of topics that might be covered if they are relevant for the particular project or product. For example, if the system is a standalone software not communicating with any other system, it does not make any sense to include a section 'Software Interfaces'. Some parts might be skipped, and some might just reference other documents or sources (for instance, if the scope is defined by a set of use cases included in the separate use case document).

Glossary

List of terms used in the document, such as processes, systems, etc. Preferably just references to the central glossary.

List of Abbreviations

List of abbreviations used in the document. Preferably just references to the central glossary.

1. Overall Description

This section aims to provide information about why the new software, or a modification of the existing one, is needed. It also introduces the problem the software is expected to solve and describes the environment in which it will operate.

1.1 System/Application Overview

This section aims to put the future system in a context and to explain its origin. It must be clear why the system is needed and what benefits it is expected to provide. If this information is already present in other documents such as BRD or Solution description, it should not be duplicated here and should be reference instead. Outline whether it is an entirely new system, a new version of the existing one or legacy system replacement, and describe how the system fits into the overall IT architecture, including relationships to other systems, if any. This is usually best described visually, for example, using a context diagram.

1.2 User Classes

In the business analysis part, the analyst performs stakeholder analysis, which aims to discover all relevant parties which are affected by the change, including external companies and other third-party entities. In this part, the readers are interested in the actual users of the system - who will use the product and what are the typical use cases for each group. If there is a general company-wide catalog of stakeholders and user classes, this section should just reference it.

1.3 Operating Environment

Most systems, even if implemented from scratch, will be operated in an existing environment. The company will usually have defined what hardware platform they use, what operating systems they prefer, who provides the IT services to the company, or how the components are geographically distributed. All of this must be articulated as it may generate additional constraints for the solution. The contemporary systems and applications are also usually not operated in isolation, so it should be described what other systems are operated in the company with relation to the new/modified system.

1.4 Design and Implementation Constraints

Describe programming languages, libraries or frameworks which are prescribed to be used, integration constraints (such as communication protocols) or development methodology which is required for the particular project.
Please note this section does not describe business constraints that are captured in the BRD.

1.5 Assumptions and Dependencies

When implementing a solution, some aspects cannot be guaranteed for the future, so analysts must make assumptions. As there is a chance that the assumption will turn out to be false in the end, assumptions generate project risks. For example, we can just assume that the graphic studio will deliver the final GUI designs before the development starts so that developers will not be forced to implement the GUI twice. Since this assumption generates potential risk, the essential part of this assumption should be a statement of how the associated risk could be mitigated - the team will be performing interim GUI designs delivery checks.
Dependencies represent constraints that may affect development. For example, if the development could not start without delivering the GUI designs, it would present a dependency.
Please note this section does not describe business assumptions and dependencies that are captured in the BRD.

2. Functional Specification

This section defines the capabilities required from the system, and together with the Data Specification, it represents a core part of the system analysis. It is crucial to know what the user should be able to do with the system, what functions the system should provide, and what data the system will need to manage. The capabilities can be described on many levels of abstraction. For example, they could be first captured in the form of very high-level features described in the Solution Description, then broken down into main usage scenarios described using use cases and then elaborated in detail that is sufficient for implementation. This could present a lot of information, so for large enterprise systems, the functional specification could be a separate document.

Different types of capabilities require different forms of description, but all of them share the same principle - there is always one central element around which the detailed specification is built up. It could be a use case, a process step, or an event to which the system must respond. This element then serves as a hub connecting all information required for the development. Which element will be the hub depends on the nature of the system. If it is a system for end-users, it might be a use case or a feature. If the system is process-oriented, the most important aspects of the system are not features but the process steps and transitions between them. And for systems without a user interface, which just responds to some incoming event, the central element will be the event.

If the number of system capabilities in the functional specification is not trivial, some kind of structuring needs to be put in place. Typically the capabilities are organized in logical units such as system modules so that the whole specification is not a single disorganized stream of information.

3. Data Specification

Data is the core asset managed by the information systems. Understanding the data, its semantics, relationships, and the rules for manipulating it is crucial for designing any system.

3.1 Data Analysis

In this section, the system is described from the data’s point of view. Depending on the needs, it may present:

  • A high-level domain model introducing the problem domain in which the system will operate (referenced if it is a part of another document)
  • More concrete analytical/logical data models, including class diagrams or entity-relationship diagrams stating how the data will be stored in the actual system

The core part of the data analysis is a description of the entities, their attributes, and the relationships between them (data dictionary). The specification should also define which data shall be historized, which data changes shall be audited, and anticipated data access restrictions.

3.2 Data Management

Implementing a system requires not only understanding what data to store but also how the data will be initiated and managed

  • How the data will be populated once the system is deployed (one-time data load, incremental data loads, etc.)
  • How the data integrity will be assured (backups, mirroring, etc.) and what are the rules for archiving or disposing of data or its backups

4 Outputs

This section describes all outputs the system is expected to produce, such as data reports, documents, or images. But keep in mind, this does not say when and how the output is produced. It does not state which use case, algorithm or function produces the particular output. The fact that a function generates a particular image should be mentioned only in the function definition, as stating it here would mean duplicating the information. The only possibility to include the information here is linking the function to its output in the database and to automatically generate this relationship here. We will show you more about generating specifications in this chapter.

5. External Interfaces

This section describes characteristics of the interfaces through which the system will communicate with external entities, including users, external hardware, or other systems and applications. The goal is not to describe specifics of particular screens, services, or data files, but to describe general requirements. For example, the requirement to sort a customer list by the name column does not belong here and goes to the relevant screen specification. But the general instruction to have all submit buttons red will be included in this section. Similarly, the requirement to send an email after the customer is created in the database goes to the ”Create customer” use case specification, but a requirement to encrypt all email communication belongs here.

5.1 User Interfaces

Includes information and requirements related to the user interface. It typically defines user interface standards, specifics about fonts, icons, preferred colors, supported screen sizes, or whether the user interface should be ready for use by persons with specific disabilities. Its purpose is not to list all screens in the system or describe requirements or specifics of a particular screen.

5.2 Software Interfaces

This section describes which entities the system shall communicate with and how. It should be clear what is the purpose of the communication, direction of the communication, format of the communication, frequency of the communication, response times, security, etc. For example, this section may include a Client Management System requirement to get a document with a specific ID from the Document Management System. On the other hand, the CMS may be required to expose an interface through which other systems can get client information. It should be a real-time interface, the input is the client id, the output is the client information, no authentication is needed, and the peak is expected to max 10 calls per second.
Unlike the user interface screens, it is ok to have a section listing all required SW interfaces. While going through dozens of screens without the context does not bring any value, having a single place where the communication with the outside world can be reviewed is beneficial. But please note, this section provides just an overview of the required communication paths; the technical details specifying concrete protocols or security mechanisms should be included in the Communications Interfaces.

5.3 Hardware Interfaces

If the application needs to communicate with some hardware device, it must be defined what devices the system will communicate with and how the communication will be carried out, including the communication protocols, format of the messages, and other information needed to implement the integration with the device.

5.4 Communications Interfaces

Describe all possible ways the system will communicate with the outside world. Again, specify the general concepts only. Don’t list which services should be exposed using REST and which via SOAP protocol as this belongs to the particular interface specification. Just state the common requirements for the REST endpoints such as encryption or authentication method. This section specifies whether the solution will be communicating via the internet or LAN, specification of the network protocols, or what separator will be applied in the CSV files used for communication.

6. Technical Requirements and Quality Attributes

This section includes all the system's attributes, which do not relate directly to what the system shall actually do - behavior and functionality. It describes how effective the solution must be or what qualities it should have. The list can specify how the system shall perform, how stable it should be, or what are the security requirements.

Examples:

  • Capacity Requirements
  • Performance Requirements
  • Reliability Requirements
  • Security Requirements
  • Testability
  • Stability
  • Security
  • Etc.

7. Other

This section includes specifications that do not fit into any other category and may be omitted if it is not necessary for the case. For example, if all applications in the company are implicitly in English with the US date, time, and currency formats, the Internationalization and Localization section is not needed unless it is required to be explicitly emphasized.

  • Transition requirements
    • Includes everything which is needed for the successful implementation and deployment of the new system. Transition requirements address topics such as data conversion, training, and business continuity. For example, to deploy the new solution, some utility application for converting the old database to the new format must be developed. Temporary interfaces might be needed, or it might be required that the system must be able to run in parallel with the old solution for a limited time.
    • Transition requirements are only temporary and they become invalid once the system is successfully deployed
    • Transition requirements may also include requirements for training, hiring new people, etc. However, these should not be part of a system specification but rather project management documents
  • Internationalization (which languages the system should be translated to) and localization (which locales such as date, time and money formats it must support)
  • Monitoring, logging
    • Specific requirements for logging and monitoring the system such as the format or frequency
  • Requirements defining the preferred way the system must be installed, configured, or run. For example, the system must have a graphical user interface for the installation and the basic configuration.