Software requirements specification done right

A software requirements specification (SRS) is a formal document that describes what a software system shall do, how it shall behave under specified conditions, and the constraints it operates under. The current standard is ISO/IEC/IEEE 29148:2018. It replaced IEEE 830-1998. Most templates you find online still mirror the 1998 version. That standard is more than a quarter-century out of date.

This article explains what actually belongs in an SRS. It covers how to write requirements a tester can verify, and how to keep the document current after the first release ships. We assume you have written something requirements-shaped before: a feature spec, a PRD, or an RFC. You want to do it more rigorously.

What an SRS is, and what it is not

An SRS describes the software at the level of "the system shall." It is a specification, not a sales pitch. Three traits distinguish it from a product requirements document (PRD), a business requirements document (BRD), or a feature brief:

1. Every requirement is independently verifiable. A tester or auditor can point at the running system and decide pass or fail.
2. Requirements are atomic. One sentence, one requirement, one identifier.
3. The document is traceable. Each requirement links upward to a stakeholder need and downward to design elements and test cases.

If a paragraph fails any of these tests, it belongs in a different document.

The current standard: ISO/IEC/IEEE 29148:2018

Most "SRS template" results still parrot IEEE 830-1998. That standard was withdrawn in 2011. Its replacement is ISO/IEC/IEEE 29148:2018, "Systems and software engineering — Life cycle processes — Requirements engineering." The 2018 revision supersedes the original 2011 version of 29148.

The standard separates three related documents:

Most templates on the internet are a hybrid: partly stakeholder needs, partly system-level functions, partly software requirements. That conflation is the single most common reason SRS documents become unreadable. Pick a scope and stay in it.

What goes in each section

ISO/IEC/IEEE 29148:2018 specifies a structure for the SRS. Trimmed of standards jargon, it looks like this:

1. Introduction — purpose, scope, definitions, references, overview of the document.
2. References — every standard, contract, interface specification, or upstream requirements document this SRS depends on.
3. Specific requirements — the heart of the document. Functional requirements, performance requirements, external interfaces, internal interfaces, operational requirements, system modes, design constraints, software quality attributes (security, reliability, maintainability, portability), and supporting information.
4. Verification — for each requirement, the method by which it will be verified: test, inspection, analysis, or demonstration.
5. Annexes — assumptions, dependencies, traceability matrices, glossary.

Section 3 is where the work happens. The rest is scaffolding.

Writing functional requirements

A functional requirement states what the software shall do, in a form a tester can verify. The most reliable way to write one is the Easy Approach to Requirements Syntax (EARS). Alistair Mavin and colleagues introduced it at the 2009 IEEE International Requirements Engineering Conference.

EARS uses five patterns:

A bad requirement and its EARS-shaped replacement:

Bad: The system should handle login attempts efficiently and provide user-friendly error messages.

Good: When a user submits invalid credentials, the authentication service shall return HTTP 401 within 200 ms and display the message "Email or password is incorrect."

The bad version contains four problems. "Should" is not normative ("shall" is). "Efficiently" is unmeasurable. "User-friendly" is subjective. And it bundles two behaviors into one sentence: response time and error display. The good version is atomic, verifiable, and unambiguous.

Writing non-functional requirements

Non-functional requirements describe how well the system performs its functions, not what those functions are. ISO/IEC 25010:2011 gives a working taxonomy: performance efficiency, compatibility, usability, reliability, security, maintainability, and portability.

Non-functional requirements fail when they are aspirational rather than measurable. Three rewrites:

Aspirational: The system shall be highly available.

Measurable: The system shall maintain 99.9% availability measured monthly over the production environment, excluding scheduled maintenance windows announced 48 hours in advance.

Aspirational: The system shall be secure.

Measurable: The system shall encrypt all data in transit using TLS 1.3 or higher and shall pass an OWASP ASVS Level 2 audit before each major release.

Aspirational: The system shall be easy to use.

Measurable: A first-time user shall complete the account creation flow in fewer than 90 seconds with no external assistance, measured against a sample of 20 users in moderated usability testing.

A non-functional requirement that cannot be measured is not a requirement. It is a wish.

Interface and constraint requirements

These are the sections most templates omit and the ones that cause the most trouble during implementation review.

External interface requirements specify how the software communicates with the world outside it: users, other systems, hardware, and the network. Each external interface gets its own subsection with a defined protocol, data format, error handling, and version. A REST API requirement, for example, names the endpoint, HTTP method, request and response schemas, authentication mechanism, and rate limit.

Internal interface requirements specify how subsystems within the software communicate with each other. These matter when the project is large enough that different teams own different subsystems. A small product can skip this.

Design and construction constraints record decisions the software must respect even when they are not strictly behavioral. They cover programming language, runtime environment, third-party libraries that may or may not be used, data residency rules, and accessibility conformance level. "The implementation shall use Java 21 LTS" is a constraint. So is WCAG 2.2 AA.

These three sections are where compliance audits live. Skipping them is the most expensive mistake you can make on a regulated product.

Traceability: how requirements connect to everything else

Traceability is the practice of linking each requirement to the stakeholder need that motivated it, the design element that implements it, and the test case that verifies it. ISO/IEC/IEEE 29148:2018 requires bidirectional traceability for compliant SRS documents.

A traceability matrix typically has columns for:

• Requirement ID and brief description
• Source (stakeholder need, regulation, upstream system requirement)
• Design element (module, class, service)
• Verification method (test case ID, inspection record, analysis result)
• Status (proposed, approved, implemented, verified, deferred)

In structured authoring tools, traceability is a relationship between content objects, not a spreadsheet column. Each requirement is a topic with typed links to its design and test counterparts. When a requirement changes, the affected design topics and test topics surface automatically. We built Topicary around this model. Each requirement is a reusable, linkable topic, and the version manager creates a named baseline for every release.

Traceability matters most when somebody asks "if we change requirement R-217, what else has to change?" A spreadsheet answers that question slowly. A structured content graph answers it in one query.

SRS in agile teams

The conventional wisdom is that agile teams do not need an SRS. The conventional wisdom is wrong for four concrete cases:

• Regulated industries. Medical devices (IEC 62304), avionics (DO-178C), automotive (ISO 26262), nuclear (IEC 60880), and rail (EN 50128) all require a documented, traceable requirements specification. Development methodology does not enter into it. The auditor does not care that you do two-week sprints.
• Contractual development. Fixed-price contracts, RFP responses, and most government work require an SRS as a deliverable.
• Safety-critical or high-stakes systems. Insurance underwriting, financial settlement, healthcare records, anywhere a failure has named consequences.
• Multi-team coordination. When more than three teams build against the same system, an SRS is cheaper than the alignment meetings.

The realistic question is not "SRS or backlog?" It is "how do we maintain an SRS that stays in sync with a backlog?" Two patterns work:

1. The SRS is generated from the backlog. Each user story carries a requirement ID. A periodic build process aggregates approved stories into the SRS structure.
2. The SRS is the source, the backlog is the work plan. Each backlog item references one or more SRS requirements. The SRS changes through a controlled change process. The backlog reflects the work to make the software match.

Either pattern beats the third option, which is maintaining the SRS and the backlog independently. That is how SRS documents go stale.

Why SRS documents go stale (and how to stop it)

An SRS becomes obsolete for three reasons, in this order:

1. The document lives in a tool that does not support reuse. Word and PDF SRS documents duplicate content. When a single requirement changes, the writer has to find every occurrence and update them in lock step. That means the SRS, the test plans, the design documents, and the release notes. They will miss at least one.
2. The document has no review cadence. If no calendar event forces a review, the document drifts from reality at the rate the software changes.
3. The document is not the source of truth. Developers consult Slack threads, Confluence pages, and ticket comments instead of the SRS. The SRS becomes ceremonial.

The first reason is mechanical. A component content management system stores each requirement as a reusable component. When the requirement changes once, every document that references it updates automatically. The same approach makes structured authoring practical without DITA XML for teams that cannot adopt the full toolchain.

The second and third reasons are organizational. They get easier once the mechanical problem is solved. Reviewing a structured document with a known change set is a 30-minute meeting. Reviewing a 90-page Word document where you have to diff against last quarter's version is an afternoon nobody volunteers for.

A practical SRS outline

If you are starting an SRS today, use this outline. It conforms to ISO/IEC/IEEE 29148:2018 and removes sections most software teams never use.

1. Introduction
   1.1 Purpose
   1.2 Scope (what is in, what is out)
   1.3 Definitions, acronyms, and abbreviations
   1.4 References
   1.5 Document overview

2. System overview
   2.1 System context and stakeholders
   2.2 System functions (one-paragraph summary)
   2.3 User characteristics
   2.4 Operating environment
   2.5 Assumptions and dependencies

3. Specific requirements
   3.1 Functional requirements (grouped by feature area)
   3.2 Performance requirements
   3.3 External interface requirements
       3.3.1 User interfaces
       3.3.2 Hardware interfaces
       3.3.3 Software and API interfaces
       3.3.4 Communication interfaces
   3.4 System modes and states
   3.5 Design and construction constraints
   3.6 Software quality attributes
       3.6.1 Reliability
       3.6.2 Availability
       3.6.3 Security
       3.6.4 Maintainability
       3.6.5 Portability
       3.6.6 Accessibility

4. Verification
   4.1 Verification methods by requirement
   4.2 Verification cross-reference table

5. Annexes
   A. Traceability matrix
   B. Glossary
   C. Change log

Three things to notice. Section 3 is the only section that grows with the size of the system. Everything else stays roughly constant. Section 4 is required by the standard and routinely omitted by template authors. The change log in Annex C separates a living document from an artifact. It answers the question "what changed since we last looked at this?"

SRS, PRD, and BRD compared

These three documents are routinely confused. The short version:

A small team typically collapses these into one document. A regulated team keeps them separate because each has a different audit trail. Dedicated templates exist for the PRD and BRD, and SRS vs PRD vs BRD compares all three in depth.

Tooling

Three categories of tool make sense for SRS authoring:

1. General word processors (Microsoft Word, Google Docs). Cheapest. Fine for the first 20 requirements. Painful past 100.
2. Requirements management tools (IBM DOORS, Jama Connect, Polarion). Built for traceability and compliance. Expensive, with a steep onboarding curve. The right choice for safety-critical work.
3. Structured authoring and CCMS platforms (Topicary, MadCap Flare, Heretto, Paligo). Treat each requirement as a reusable topic, support multi-channel publishing, and maintain a content graph for traceability. The right choice for software teams whose SRS is one document among dozens.

For a broader survey, our technical writing software comparison covers the full picture across these categories. For documentation version control specifically, structured tools beat Word both on diff granularity and on baseline management.

FAQ

Is IEEE 830 still a valid SRS standard?

No. IEEE 830-1998 was withdrawn in 2011 when it was replaced by IEEE 29148-2011, which has itself been revised as ISO/IEC/IEEE 29148:2018. Templates that still cite IEEE 830 are using a standard that is more than fourteen years out of currency. The new standard reorganizes the document, adds verification as an explicit section, and integrates with the broader ISO/IEC/IEEE 15288 systems engineering lifecycle.

How long should an SRS be?

It depends on the complexity of the system and the regulatory context. A small SaaS feature might have a 15-page SRS with 60 to 80 requirements. A safety-critical embedded system can run to 300+ pages with thousands of requirements. Length is not a quality signal. A 200-page SRS that fails verification because half its requirements are unmeasurable is worse than a 30-page one that passes.

Do we need an SRS if we use Jira and user stories?

For most regulated, contractual, or multi-team work, yes. User stories capture user intent at the level of "as a user I want." An SRS captures system behavior at the level of "the system shall." The two are complementary. The pattern that works is to maintain the SRS as the source of truth and use stories as the work plan, with each story referencing the requirements it implements.

What is the difference between a functional requirement and a use case?

A functional requirement is a single, atomic statement of what the system shall do. A use case is a sequence of interactions between actors and the system that achieves a goal. One use case typically generates multiple functional requirements, one per step the system performs. Use cases are useful for elicitation; functional requirements are what gets verified.

Who should own the SRS?

In a regulated context, the systems engineering or quality function owns it because the audit trail flows through them. In a non-regulated software team, the lead engineer or technical product manager usually owns it, with reviews by architecture, QA, and security. The owner is whoever is accountable for the document being correct on the day someone asks.

How frequently should we review an SRS?

At a minimum, before each major release. In practice, the right cadence is whichever review process you are already running for other engineering artifacts: design reviews, sprint reviews, change control board meetings. The goal is that no requirement goes more than one quarter without somebody confirming it still reflects the system. If you cannot meet that bar, the document will drift.

Sources

• ISO/IEC/IEEE 29148:2018, "Systems and software engineering — Life cycle processes — Requirements engineering," International Organization for Standardization, 2018. https://www.iso.org/standard/72089.html
• IEEE 830-1998, "IEEE Recommended Practice for Software Requirements Specifications" (withdrawn 2011), Institute of Electrical and Electronics Engineers, 1998.
• Mavin, A., Wilkinson, P., Harwood, A., Novak, M., "Easy Approach to Requirements Syntax (EARS)," 17th IEEE International Requirements Engineering Conference, 2009.
• INCOSE, "Guide for Writing Requirements," International Council on Systems Engineering, version 4, 2023.
• ISO/IEC 25010:2011, "Systems and software Quality Requirements and Evaluation (SQuaRE) — System and software quality models," International Organization for Standardization, 2011.