USER REQUIREMENTS statements in NATURAL LANGUAGE plus diagrams, describing the services the system provides and its operational constraints. AUDIENCE: client managers, system end-users, client engineers, contract managers, system architects → readers who need to understand SCOPE and AGREE to it, and who may have no technical background · written from the USER's viewpoint · abstract, avoiding implementation detail · typically numbered paragraphs of prose EXAMPLE (user requirement): "4.1 The system shall allow a licence applicant to check the status of their application at any time." SYSTEM REQUIREMENTS a DETAILED, structured description of the system's functions, services and operational constraints. Defines what should be IMPLEMENTED, and may form part of the contract. AUDIENCE: system end-users, client engineers, system architects, SOFTWARE DEVELOPERS → readers who must build or verify it · written from the SYSTEM's viewpoint · precise and complete enough to design from · may use structured notation, tables, models EXAMPLE (the same requirement, expanded): "4.1.1 On receiving a status request containing a valid 12-digit application number, the system shall return the current status code, the date it was set and the name of the officer who set it. 4.1.2 If the application number is not found, the system shall return error code 404 with the message 'Application not found'. 4.1.3 The status shall be one of: RECEIVED, UNDER_REVIEW, APPROVED, REJECTED, ISSUED. 4.1.4 A status request shall complete within 1 second for 99% of requests, measured at the server. 4.1.5 Status requests shall be logged per requirement 7.3." ONE user requirement became FIVE system requirements. That expansion ratio is normal, and it is where ambiguity gets removed. WHY BOTH ARE NEEDED — and the trap: A common failure is to write only user requirements and let developers "figure out the details". The details then get decided implicitly, differently by each developer, and the inconsistencies surface at integration. The opposite failure is to write only system requirements. The customer cannot verify that they describe what was asked for, so they sign something they do not understand.

Natural language is the default because everyone can read it. It is also the source of most requirements defects. 1. AMBIGUITY — the same words read differently "The system shall notify the user and the administrator when a transaction fails." → notify BOTH, or EITHER? Does "when a transaction fails" mean at the moment of failure, or in a daily summary? 2. LACK OF PRECISION "The system shall handle large files efficiently." → large = 10 MB or 10 GB? efficiently = compared to what? 3. REQUIREMENTS CONFLATION several requirements bundled in one paragraph, so they cannot be individually traced, tested or changed: "The system shall validate the applicant's identity against the national database, record the result, and email a confirmation within 24 hours." → that is THREE requirements. If the email requirement changes, which paragraph do you edit? 4. REQUIREMENTS AMALGAMATION functional and non-functional mixed together, so the architect cannot extract the constraints. 5. THE WORD "SHALL" vs "SHOULD" vs "WILL" A convention exists and should be followed: SHALL a binding requirement SHOULD a desirable goal, not binding WILL a statement of fact or intent, not a requirement Using them loosely makes it impossible to tell what is contractual. 6. VAGUE QUANTIFIERS to avoid entirely: "as appropriate", "if possible", "user-friendly", "efficient", "flexible", "state-of-the-art", "improved", "minimal impact", "etc." Each one moves a decision from the requirements document to an argument later. STRUCTURED ALTERNATIVES that reduce ambiguity: STRUCTURED NATURAL LANGUAGE — a fixed template per requirement: function, description, inputs (and their source), outputs (and destination), action, preconditions, postconditions, side effects FORM-BASED SPECIFICATION — the same, as a filled form. Forces completeness, because a blank field is visible. TABULAR SPECIFICATION — best for complex conditional logic, because a table makes MISSING CASES obvious: condition action ──────────────────────────────────────────────── balance ≥ amount, account open execute transfer balance < amount, account open reject: insufficient balance ≥ amount, account frozen reject: account frozen balance < amount, account frozen reject: account frozen A prose version would almost certainly omit one row. GRAPHICAL MODELS — use case diagrams, sequence diagrams, state machines. Good for showing FLOW and STATE, poor for detail. MATHEMATICAL / FORMAL SPECIFICATION — Z, VDM, B, Alloy. ✔ unambiguous, and provable ✗ few engineers and almost no customers can read it, so it cannot serve as the agreed document → used for safety-critical kernels only

A STRUCTURED SPECIFICATION, worked: ───────────────────────────────────────────────────────── FUNCTION Compute daily interest for a savings account DESCRIPTION Calculates interest accrued on the closing balance of the previous business day. INPUTS account_number : 12 digits, from the account master date : a business date SOURCE Account database (see section 6.2) OUTPUTS interest_amount : NUMERIC(12,2), in NPR computed_on : timestamp DESTINATION Interest ledger (see section 6.5) ACTION interest = closing_balance × (annual_rate/365) rounded to 2 decimal places, half-up REQUIRES the account exists and is not closed; a closing balance exists for the given date PRECONDITION account status ∈ {ACTIVE, DORMANT} POSTCONDITION one ledger entry exists for (account, date); the account balance is UNCHANGED by this function SIDE EFFECTS none ───────────────────────────────────────────────────────── NOTICE WHAT THE TEMPLATE FORCED: · the rounding rule — prose would have said "calculate interest" and left this to whoever coded it, producing a one-paisa discrepancy nobody could explain · the day-count convention (365, not 360 — a real banking distinction) · that the balance is NOT updated here, preventing a whole class of double-counting bug · which document defines the input and output stores, giving traceability The template's value is not tidiness — it is that each empty field is a question somebody must answer before coding, rather than after.