How to write and structure worthwhile SRS documentation

How to write SRS documentation

Formal SRS documentation generally includes these major sections, followed by supporting content: an introduction, descriptions and requirements.

Introduction

Start with a detailed introduction that provides an overview of the document. Typically, an introduction leads with a purpose and audience for the SRS and discusses the product's scope, including its benefits and goals.

The introduction should include a section that clarifies definitions, acronyms and abbreviations contained in the SRS, to avoid ambiguity. Another section of the introduction includes annotated references of any documents or other source material referenced in the SRS.

Finally, conclude the introduction with an overview of the rest of the SRS, and explain its arrangement. Again, keep the introduction focused on the SRS document -- not the software.

Descriptions

SRS documentation typically outlines software details in its second section. Include detailed descriptions of the product, functions and users. This section also contains software constraints, dependencies and roadmaps -- sometimes called apportioning of requirements.

The product description explains how the software in this project relates to other software. For example, if the software is a component of a larger platform, the SRS should explain how that platform works and its broad requirements, as well as any interfaces and dependencies -- similar to a block diagram description.

The description portion of SRS documentation should cover:

• system interfaces;
• UIs, such as the GUI and basic operations;
• hardware and network interfaces, such as required ports and protocols;
• OSes or databases;
• system memory demands and constraints; and
• site-specific requirements, such as prevailing alarm values and sensor installation.

Next, a description should detail the principal functions the software performs. The SRS document of a billing system, for instance, might detail customer invoice preparation, customer statements and customer data entry. After that, include a brief overview of user characteristics that explains the level of education and expertise expected of each user type when they interact with the product.

Finally, conclude the description with limitations that affect the software's development. These constraints might include regulatory policies, corporate governance or auditing requirements, hardware requirements, and reliability plus security elements -- any important factors that affect developers' implementation choices. Don't forget an outline of assumptions and dependencies, such as a certain OS or hardware platform the team plans to use.

Requirements

Use the third portion of the SRS document to outline requirements for the software. It is the largest and most vital part of the document. Provide enough detail here to inform the team on how to build the software and create tests to verify that software meets its requirements. Phrase the requirements as tangible tasks that users and systems can see and act upon.

Outline the external interface requirements first; describe the various inputs and outputs. These details usually include information about the signals, such as name; purpose; source or destination; units; timing; command and data formats; and display characteristics.

Next, break down the Functional requirements of the software. Define all of the basic activities that must occur to receive inputs, act upon those inputs and then produce outputs. Functional requirements include many criteria, such as input checking, operational sequences, communication, storage, error handling, formulas and transforms. If a database supports functions, describe the data composition. Database content might include the information those functions use, data relationships, access requirements and retention requirements.

Performance requirements detail practical and measurable aspects of the software's capacity. These factors include the acceptable number of simultaneous users, the number of transactions per second and the volume of data processed over time. Cover tolerances and target windows -- for example, 90% of all transactions shall process in less than two seconds. These requirements are critical for software design and testing.

If software is subject to compliance or regulatory oversight, the SRS should lay out how to support compliance, such as transaction reports, logging, audits and accounting. Include additional software requirements for reliability factors, availability, security and portability.

Indexes and appendices

Finally, conclude the SRS with a variety of supporting information that helps the reader follow and use the document. You could add a table of contents, an index or any other relevant supporting content in the form of appendices. An appendix could contain survey results, sample input or output formats, or background information related to the problem or opportunity that the software intends to address.

Organize an SRS document

SRS writers use various approaches to organize software requirements, which can be highly detailed and extensive. Aim to make these requirements as clear and relevant to the customer as possible.

For example, you can organize an SRS by mode to describe behaviors and requirements that depend on how the software operates at a given time. For example, documentation for an industrial control system will detail how it works in training, normal and emergency operating modes. Software requirements can vary substantially for each mode.

You can also organize an SRS by user type or class. A retail point-of-sale software system might provide different capabilities based on whether the user is a regular employee, supervisor, manager or administrator.

The SRS for some software projects is best organized around the objects that input data to it, covering those system attributes and functions or services. Consider an industrial monitoring system: It must offer completely different interfaces and capabilities to the users, sensor-based devices that perform monitoring, alarms and response tools.

Some writers organize SRS documentation by feature. Each feature is a service or capability activated by a series of conditions. A business telephone system is a feature-based system, wherein descriptions and requirements relate to incoming calls, outgoing calls, call forwarding and conference calls.

An SRS can also include a theme, such as stimulus and response. Industrial control software documentation might describe and sort by stimuli, like pressure, temperature, frequency and valve states. A response-based SRS outline might apply to a reporting software package organized by configuration, report generation and visualizations.