Organizing Requirements for Complex Systems

Key ideas#

Why one document is rarely enough#

Leffingwell and Widrig list the usual reasons:

the system is very complex;
customer needs are documented well before detailed requirements;
the system is one of a family of related products;
the release being built implements only part of the known requirements;
business and marketing goals need to be kept apart from detailed product requirements.

Wiegers and Beatty reach the same conclusion from the other side: there is no fixed rule of one specification per project, and very large systems often need a system-level specification plus subordinate ones.

A hierarchy for systems of subsystems#

For complex hardware and software systems, Leffingwell and Widrig describe a recursive structure:

A system-level specification describes the external behaviour of the whole system, without regard to how it will be split up.
Once those requirements are agreed, designers partition the system into subsystems, and each subsystem gets its own specification of its external behaviour.
Partitioning creates a new class of requirements: derived requirements, including the interfaces between subsystems, which act as contracts between them.
The process repeats at the next level down.

Specifications that are refined further are called system requirements specifications. The ones at the bottom, not decomposed further, are hardware or software requirements specifications.

Requirements for a product family#

When several products share functions and exchange data, the authors suggest this set:

a family vision document describing how the products work together and which functions they share;
use cases showing how users interact with the products working together;
a specification for shared software, such as common menus and communication protocols;
for each product, its own vision document, specification and use case model for what is specific to it.

Each product specification can either reference the family documents, so a change is made in one place but you need a tracing tool to follow it, or repeat the shared requirements, which is simpler without a tool but creates duplication to keep in step.

Future requirements#

Some requirements are found early but do not belong in the current release. You should neither put them into the specification as if they were planned (that makes the scope unclear) nor throw them away (they are valuable, and knowing them lets designers build in flexibility). Record them in the same document, clearly marked as not planned for this release.

Marketing requirements versus product requirements#

A marketing requirements document (MRD) captures the business side separately from the specification: target markets and segments, user classes, competitors and how the product differs, the usage environment, costs, pricing and distribution. It supports the go or no-go decision and lets customers and developers confirm their understanding of the product early. The MRD is not part of the specification, but it should come before it and justify it.

How to apply it#

List what you have: one product or several, one system or a system of subsystems, one release or many.
Write the business view first. For a market product, start with an MRD or a vision document; for a family, a family vision.
Agree system-level requirements before partitioning. Do not let subsystem teams write their own specifications until the external behaviour of the whole is settled.
Record derived requirements explicitly, especially interfaces between subsystems, and give each interface an owner on both sides.
Choose reference or repeat for product families based on whether you have a tool that can trace across documents.
Add a future requirements section with its own status, so nobody mistakes it for committed scope.
Trace downward: every subsystem requirement should link to a system requirement or be marked as derived.

Example#

The Workshop (a fictional bike-repair chain) is planning three related products: a customer booking site, a mechanics’ tablet app for updating repair status, and a parts-ordering tool for managers. They share customer and repair data and a notification service.

Family vision: how the three products work together, for example a repair moving from “booked” to “in progress” to “ready” across all three.
Shared specification: the notification service and the shared repair record.
Per product: a short vision and specification for what is unique, such as slot selection on the booking site or supplier catalogue search in the parts tool.
Future requirements: loyalty discounts, recorded in the booking site specification and marked as not planned for release 1.

The team has no cross-document tracing tool, so the product specifications reference the shared specification by section number and the analyst checks those references at each baseline.

Pitfalls#

Subsystem specifications written before system requirements are agreed. Each team optimizes locally and interfaces conflict.
Interfaces treated as nobody’s job. Derived interface requirements need an owner on each side.
Future ideas mixed into committed scope. Mark them, or developers will build them or testers will test for them.
Business arguments embedded in the specification. Keep pricing and market reasoning in the MRD or vision.

Sources and further reading#

D. Leffingwell, D. Widrig. Managing Software Requirements: A Unified Approach. Addison-Wesley, 2000, ch. 16.
K. Wiegers, J. Beatty. Software Requirements, 3rd ed. Microsoft Press, 2013, ch. 10 (how many specifications a project needs).