The best way to predict the future is to invent it… : June 2011

y Donn Le Vie, Jr.

Here's the scenario: You're finishing up your latest HTML Help project...no more late nights or weekends...back to a "normal" 50-hour work week. That's when the development team lead strolls into your office and says she just got your manager's okay for you to help the development team "put together the functional requirements specification template for the next major project."

"A what?" you ask with a look of semi-shock. Panic sets in. "What did I do to deserve this? I don't even know where to start! Maybe someone on the TECHWR-L list can help...."

For technical writers who haven't had the experience of designing software requirements specifications (SRSs, also known as software functional specifications or system specifications) templates or even writing SRSs, they might assume that being given the opportunity to do so is either a reward or punishment for something they did (or failed to do) on a previous project. Actually, SRSs are ideal projects for technical writers to be involved with because they lay out the foundation for the development of a new product and for the types of user documentation and media that will be required later in the project development life cycle. It also doesn't hurt that you'd be playing a visible role in contributing to the success of the project.

This article will describe what an SRS is and why it's important, discuss how and why technical writers should be involved with them, and discuss the critical elements for writing an SRS. Although this article does not attempt to address all aspects of developing SRSs, it aims to help you determine the scope for such a project, to provide some guidelines for writing SRSs, and to provide additional resources. Hopefully with this information, you'll not be asking, "Why me?" but proclaiming "Why not me?"

What is a Software Requirements Specification?

An SRS is basically an organization's understanding (in writing) of a customer or potential client's system requirements and dependencies at a particular point in time (usually) prior to any actual design or development work. It's a two-way insurance policy that assures that both the client and the organization understand the other's requirements from that perspective at a given point in time.

The SRS document itself states in precise and explicit language those functions and capabilities a software system (i.e., a software application, an eCommerce Web site, and so on) must provide, as well as states any required constraints by which the system must abide. The SRS also functions as a blueprint for completing a project with as little cost growth as possible. The SRS is often referred to as the "parent" document because all subsequent project management documents, such as design specifications, statements of work, software architecture specifications, testing and validation plans, and documentation plans, are related to it.

It's important to note that an SRS contains functional and nonfunctional requirements only; it doesn't offer design suggestions, possible solutions to technology or business issues, or any other information other than what the development team understands the customer's system requirements to be.

A well-designed, well-written SRS accomplishes four major goals:

It provides feedback to the customer. An SRS is the customer's assurance that the development organization understands the issues or problems to be solved and the software behavior necessary to address those problems. Therefore, the SRS should be written in natural language (versus a formal language, explained later in this article), in an unambiguous manner that may also include charts, tables, data flow diagrams, decision tables, and so on.
It decomposes the problem into component parts. The simple act of writing down software requirements in a well-designed format organizes information, places borders around the problem, solidifies ideas, and helps break down the problem into its component parts in an orderly fashion.
It serves as an input to the design specification. As mentioned previously, the SRS serves as the parent document to subsequent documents, such as the software design specification and statement of work. Therefore, the SRS must contain sufficient detail in the functional system requirements so that a design solution can be devised.
It serves as a product validation check. The SRS also serves as the parent document for testing and validation strategies that will be applied to the requirements for verification.

SRSs are typically developed during the first stages of "Requirements Development," which is the initial product development phase in which information is gathered about what requirements are needed--and not. This information-gathering stage can include onsite visits, questionnaires, surveys, interviews, and perhaps a return-on-investment (ROI) analysis or needs analysis of the customer or client's current business environment. The actual specification, then, is written after the requirements have been gathered and analyzed.

Why Should Technical Writers be Involved with Software Requirements Specifications?

Unfortunately, much of the time, systems architects and programmers write SRSs with little (if any) help from the technical communications organization. And when that assistance is provided, it's often limited to an edit of the final draft just prior to going out the door. Having technical writers involved throughout the entire SRS development process can offer several benefits:

Technical writers are skilled information gatherers, ideal for eliciting and articulating customer requirements. The presence of a technical writer on the requirements-gathering team helps balance the type and amount of information extracted from customers, which can help improve the SRS.
Technical writers can better assess and plan documentation projects and better meet customer document needs. Working on SRSs provides technical writers with an opportunity for learning about customer needs firsthand--early in the product development process.
Technical writers know how to determine the questions that are of concern to the user or customer regarding ease of use and usability. Technical writers can then take that knowledge and apply it not only to the specification and documentation development, but also to user interface development, to help ensure the UI (User Interface) models the customer requirements.
Technical writers, involved early and often in the process, can become an information resource throughout the process, rather than an information gatherer at the end of the process.

In short, a requirements-gathering team consisting solely of programmers, product marketers, systems analysts/architects, and a project manager runs the risk of creating a specification that may be too heavily loaded with technology-focused or marketing-focused issues. The presence of a technical writer on the team helps place at the core of the project those user or customer requirements that provide more of an overall balance to the design of the SRS, product, and documentation.

What Kind of Information Should an SRS Include?

You probably will be a member of the SRS team (if not, ask to be), which means SRS development will be a collaborative effort for a particular project. In these cases, your company will have developed SRSs before, so you should have examples (and, likely, the company's SRS template) to use. But, let's assume you'll be starting from scratch. Several standards organizations (including the IEEE) have identified nine topics that must be addressed when designing and writing an SRS:

Interfaces
Functional Capabilities
Performance Levels
Data Structures/Elements
Safety
Reliability
Security/Privacy
Quality
Constraints and Limitations

But, how do these general topics translate into an SRS document? What, specifically, does an SRS document include? How is it structured? And how do you get started? An SRS document typically includes four ingredients, as discussed in the following sections:

A template
A method for identifying requirements and linking sources
Business operation rules
A traceability matrix

Begin with an SRS Template

The first and biggest step to writing an SRS is to select an existing template that you can fine tune for your organizational needs (if you don't have one already). There's not a "standard specification template" for all projects in all industries because the individual requirements that populate an SRS are unique not only from company to company, but also from project to project within any one company. The key is to select an existing template or specification to begin with, and then adapt it to meet your needs.

In recommending using existing templates, I'm not advocating simply copying a template from available resources and using them as your own; instead, I'm suggesting that you use available templates as guides for developing your own. It would be almost impossible to find a specification or specification template that meets your particular project requirements exactly. But using other templates as guides is how it's recommended in the literature on specification development. Look at what someone else has done, and modify it to fit your project requirements. (See the sidebar called "Resources for Model Templates" at the end of this article for resources that provide sample templates and related information.)

Table 1 shows what a basic SRS outline might look like. This example is an adaptation and extension of the IEEE Standard 830-1998:

Table 1 A sample of a basic SRS outline:
1. Introduction 1.1 Purpose 1.2 Document conventions 1.3 Intended audience 1.4 Additional information 1.5 Contact information/SRS team members 1.6 References

2. Overall Description 2.1 Product perspective 2.2 Product functions 2.3 User classes and characteristics 2.4 Operating environment 2.5 User environment 2.6 Design/implementation constraints 2.7 Assumptions and dependencies

3. External Interface Requirements 3.1 User interfaces 3.2 Hardware interfaces 3.3 Software interfaces 3.4 Communication protocols and interfaces

4. System Features 4.1 System feature A 4.1.1 Description and priority 4.1.2 Action/result 4.1.3 Functional requirements 4.2 System feature B

5. Other Nonfunctional Requirements 5.1 Performance requirements 5.2 Safety requirements 5.3 Security requirements 5.4 Software quality attributes 5.5 Project documentation 5.6 User documentation

6. Other Requirements Appendix A: Terminology/Glossary/Definitions list Appendix B: To be determined

Table 2 shows a more detailed SRS outline, showing the structure of an SRS template as found on Ken Rigby's informative Web site at http://neon.airtime.co.uk/users/wysywig/srs_mt.htm. Reprinted with permission.

Table 2 A sample of a more detailed SRS outline:
1. Scope
1.1 Identification.

Identify the system and the software to which this document applies, including, as applicable, identification number(s), title(s), abbreviation(s), version number(s), and release number(s).

1.2 System overview.

State the purpose of the system or subsystem to which this document applies.

1.3 Document overview.

Summarize the purpose and contents of this document.

This document comprises six sections:

Scope
Referenced documents
Requirements
Qualification provisions
Requirements traceability
Notes

Describe any security or privacy considerations associated with its use.

2. Referenced Documents
2.1 Project documents.

Identify the project management system documents here.

2.2 Other documents.

2.3 Precedence.

2.4 Source of documents.

3. Requirements
This section shall be divided into paragraphs to specify the Computer Software Configuration Item (CSCI) requirements, that is, those characteristics of the CSCI that are conditions for its acceptance. CSCI requirements are software requirements generated to satisfy the system requirements allocated to this CSCI. Each requirement shall be assigned a project-unique identifier to support testing and traceability and shall be stated in such a way that an objective test can be defined for it.

3.1 Required states and modes.

3.2 CSCI capability requirements.

3.3 CSCI external interface requirements.

3.4 CSCI internal interface requirements.

3.5 CSCI internal data requirements.

3.6 Adaptation requirements.

3.7 Safety requirements.

3.8 Security and privacy requirements.

3.9 CSCI environment requirements.

3.10 Computer resource requirements.

3.11 Software quality factors.

3.12 Design and implementation constraints.

3.13 Personnel requirements.

3.14 Training-related requirements.

3.15 Logistics-related requirements.

3.16 Other requirements.

3.17 Packaging requirements.

3.18 Precedence and criticality requirements.

4. Qualification Provisions To be determined.

5. Requirements Traceability To be determined.

6. Notes
This section contains information of a general or explanatory nature that may be helpful, but is not mandatory.
6.1 Intended use.

This Software Requirements specification shall ...
6.2 Definitions used in this document.

Insert here an alphabetic list of definitions and their source if different from the declared sources specified in the "Documentation standard."
6.3 Abbreviations used in this document.

Insert here an alphabetic list of the abbreviations and acronyms if not identified in the declared sources specified in the "Documentation Standard."
6.4 Changes from previous issue.

Will be "not applicable" for the initial issue.

Revisions shall identify the method used to identify changes from the previous issue.

Identify and Link Requirements with Sources

As noted earlier, the SRS serves to define the functional and nonfunctional requirements of the product. Functional requirements each have an origin from which they came, be it a use case (which is used in system analysis to identify, clarify, and organize system requirements, and consists of a set of possible sequences of interactions between systems and users in a particular environment and related to a particular goal), government regulation, industry standard, or a business requirement. In developing an SRS, you need to identify these origins and link them to their corresponding requirements. Such a practice not only justifies the requirement, but it also helps assure project stakeholders that frivolous or spurious requirements are kept out of the specification.

To link requirements with their sources, each requirement included in the SRS should be labeled with a unique identifier that can remain valid over time as requirements are added, deleted, or changed. Such a labeling system helps maintain change-record integrity while also serving as an identification system for gathering metrics. You can begin a separate requirements identification list that ties a requirement identification (ID) number with a description of the requirement. Eventually, that requirement ID and description become part of the SRS itself and then part of the Requirements Traceability Matrix, discussed in subsequent paragraphs. Table 3 illustrates how these SRS ingredients work together.

Table 3 This sample table identifies requirements and links them to their sources

http://www.techwr-l.com/techwhirl/magazine/writing/softwarerequirementspecs.html