Requirements analysis and the requirements model

Analysis modelling is a bridge, not a container

Requirements engineering hands you a pile of agreed statements: what stakeholders say they need, what the system must not do, what the deadline is worth. Requirements analysis turns that pile into a model — a set of representations of the software's operational characteristics, of its interfaces to the other elements of the system, and of the constraints it must meet. Above the model sits a system-level description written in the customer's language, covering hardware, people and business process as well as software. Below it sits the design model, which says how the software will be built. The requirements model is the bridge between them, and every element of it must be traceable down into a design element and up to something a stakeholder actually asked for. Analysis and design do bleed into one another — some design happens while you model, some analysis happens while you design — but the direction of traceability never changes.

Three objectives, each with a usable test

The model has to achieve three things, and each gives you a test you can apply to a candidate diagram:

1. Say what the customer wants. Could the customer read this element and say yes, that is my business?
2. Give the design something to start from. Does a designer get something to elaborate, rather than something to re-derive?
3. State requirements the built system can be checked against. Can you write an acceptance test straight off this element?

An element that fails all three is decoration. Delete it, and you have lost nothing but drawing time.

Rules of thumb

• Model what, not how. What interactions occur, what objects the system manipulates, what functions it performs, what behaviour it exhibits, what constraints apply.
• Stay in the problem domain, and keep the level of abstraction high.
• Delay architecture, infrastructure and non-functional detail until the design activity.
• Watch how model elements interconnect — coupling inside the model is as real as coupling in code, and a model whose elements all depend on one another cannot be changed a piece at a time.
• Provide value to every stakeholder, and keep the model as simple as it can be without sacrificing clarity.

The five modelling principles

Whatever notation you use, five operational principles hold. (1) The information domain must be represented: data flowing in, data flowing out, and data stored permanently. (2) The functions the software performs must be defined — both user-visible ones and the internal support they need. (3) The behaviour must be represented: what the software does in response to each event that reaches it from outside. (4) The models must be partitioned so that detail is uncovered in layers — divide and conquer, which is separation of concerns applied to analysis. (5) The work moves from essential information toward implementation detail: describe the essence of the problem first, and only then how a solution might realise it.

Worked example — one BorrowBox sentence, modelled

BorrowBox is a neighbourhood tool library: members reserve a power tool in an app, collect it from a bank of smart lockers with a one-time token, and return it to any free locker for a librarian to inspect. Take a single sentence from its brief — the member scans a one-time token at the locker bank and the door opens. Three principles turn it into model content. Information domain: the token, the member's identity and the reservation flow in; a door-release command and a receipt flow out; the reservation and the copy's current location are retained. Function: validate the token against a live reservation, assign a door, mark the copy checked out. Behaviour: the system rests in one state until the scan event arrives, and its response depends on whether the two-hour hold has already expired.

Now the exclusion, which is where the marks usually hide. Keep the token in an in-memory cache with a 120-second expiry answers how. The customer cannot validate it, no acceptance test follows from it, and it commits you to an infrastructure decision twelve weeks before you need to make one. It is a good idea. It is not part of the requirements model.