Requirement engineering and specification notes — Unit 2

The hardest single part of building a software system is deciding precisely what to build. Requirements Engineering (RE) is the process of defining, documenting, and maintaining requirements in the engineering design process.

⇒1.1 What is a Requirement?

A requirement is a statement of a system service or constraint. It can range from a high-level abstract statement of a service to a detailed mathematical functional specification.

⇒1.2 The Cost of Requirement Errors

Errors made during the requirements phase are the most expensive to fix. If a requirement is misunderstood, the developers will design, code, and test the wrong feature. Fixing a requirement error during the maintenance phase can cost up to 100 times more than fixing it during the requirements phase.

⇒2.1 Functional Requirements

These are statements of services the system should provide, how the system should react to particular inputs, and how the system should behave in particular situations. They define what the system does.

• Example: 'The user shall be able to search for flights using origin, destination, and date.'
• Example: 'If an invalid password is entered 3 times, the account shall be locked.'

⇒2.2 Non-Functional Requirements (NFRs)

These are constraints on the services or functions offered by the system. They often apply to the system as a whole rather than individual features. They define how well the system does it.

• Performance: 'The search results must load within 2 seconds under a load of 10,000 concurrent users.'
• Security: 'All user passwords must be hashed using bcrypt.'
• Availability: 'The system must have an uptime of 99.99%.'

Note: Failing to meet an NFR (like security) can often be more disastrous than failing to meet a specific functional requirement.

Domain requirements are derived from the application domain of the system rather than from the specific needs of system users. They may be new functional requirements, constraints on existing requirements, or define specific computations.

⇒3.1 Examples of Domain Requirements

• Healthcare (HIPAA): A medical records system must comply with strict legal regulations regarding patient data privacy.
• Banking: An accounting system must calculate interest using a specific, legally mandated mathematical formula.
• Aviation: A flight control system must use specific units of measurement to interface with legacy hardware sensors.

⇒3.2 Problems with Domain Requirements

Domain experts often leave these requirements unstated because they assume everyone knows them (e.g., a banker assumes every developer knows how compound interest works). Furthermore, they are often expressed in domain-specific jargon that software engineers do not understand.

Requirements engineering is not a single activity but a structured process consisting of four high-level sub-processes.

⇒4.1 The Four Phases

• 1. Feasibility Study: An initial study to determine if the system is worth building, technically feasible, and cost-effective. Produces a Feasibility Report.
• 2. Requirements Elicitation and Analysis: Working with stakeholders to discover what they need the system to do. This is often chaotic because users don't know exactly what they want.
• 3. Requirements Specification: Translating the gathered information into a formal, structured document (the SRS document).
• 4. Requirements Validation: Checking that the documented requirements actually define the system that the customer wants (finding errors and conflicts).

In practice, these phases are heavily interleaved and iterative. Elicitation uncovers issues that require revisiting feasibility, and validation uncovers errors that require re-elicitation.

Elicitation is the process of interacting with stakeholders to discover their requirements.

⇒5.1 Common Techniques

• Interviews: Formal or informal discussions with stakeholders. Good for general understanding, but bad for understanding complex domain rules.
• Questionnaires/Surveys: Useful when there is a large number of distributed users, but lacks the ability for deep follow-up questions.
• Observation (Ethnography): The engineer immerses themselves in the user's working environment to observe how they actually work. Extremely useful for discovering unstated/subconscious domain requirements.
• Brainstorming/JAD (Joint Application Design) Sessions: Bringing all stakeholders into a room for intense, facilitated workshops to rapidly generate requirements.
• Prototyping: Building a quick UI mockup so users have something concrete to react to.

⇒5.2 Challenges in Elicitation

Stakeholders don't know what they want. They express requirements in their own terms. Different stakeholders have conflicting requirements. Political factors may influence requirements.

Scenarios and Use Cases are highly effective ways to elicit and document requirements from an end-user's perspective.

⇒6.1 Scenarios

A scenario is a real-life example of how a system can be used. It should include:

• A description of the starting situation.
• A description of the normal flow of events.
• A description of what can go wrong and how it is handled.
• Information about other concurrent activities.
• A description of the system state when the scenario finishes.

⇒6.2 Use Cases

Use cases are a formalized way of documenting scenarios, heavily used in UML. A Use Case identifies the Actors (human users or other systems) and the Interactions they have with the system to achieve a specific goal.

Example Use Case: 'Withdraw Cash'. Actor: Bank Customer. The use case would document the main success scenario (insert card, enter pin, request money, dispense) and extensions/exceptions (wrong pin, insufficient funds).

The SRS is the official, formal document that describes the system to be developed. It serves as a contract between the client and the development team.

⇒7.1 Characteristics of a Good SRS

• Correct: Everything in the SRS accurately reflects what the software must do.
• Unambiguous: Every requirement has only one interpretation.
• Complete: All required features, constraints, and responses to invalid inputs are documented.
• Consistent: No two requirements contradict each other.
• Verifiable (Testable): There exists a finite, cost-effective process to check if the software meets the requirement.
• Traceable: The origin of each requirement is clear, and it can be tracked through design, code, and testing.

⇒7.2 IEEE 830 Standard Structure

Most SRS documents follow the IEEE 830 standard, which includes chapters for: 1. Introduction, 2. Overall Description (perspectives, user classes, constraints), 3. Specific Requirements (functional, non-functional, interfaces).

Validation demonstrates that the requirements define the system that the customer actually wants. It is the final quality assurance step on the SRS document before design begins.

⇒8.1 Validation Checks

• Validity checks: Does the system provide the functions which best support the customer's needs?
• Consistency checks: Are there any requirements conflicts?
• Completeness checks: Are all functions required by the customer included?
• Realism checks: Can the requirements be implemented given available budget and technology?
• Verifiability: Can the requirements be checked (tested)?

⇒8.2 Validation Techniques

• Requirements Reviews/Inspections: A team of reviewers manually analyzes the SRS looking for errors. This is the most common technique.
• Prototyping: Showing an executable model to users to validate their needs.
• Test-case Generation: Writing tests before writing code. If a requirement is too vague to write a test for, it is a bad requirement.

Requirements are never static. The business environment changes, new stakeholders emerge, and technology evolves. Requirements Management is the process of managing changing requirements during the requirements engineering process and system development.

⇒9.1 Traceability

Traceability is the ability to trace a requirement from its origin to its implementation and testing.

• Source Traceability: Links requirements to stakeholders who proposed them.
• Requirements Traceability: Links dependent requirements to each other.
• Design Traceability: Links requirements to the design modules and source code that implement them.

⇒9.2 Change Management Process

When a change is requested, it must be formally managed:

• 1. Problem Analysis and Change Specification.
• 2. Change Analysis and Costing (Assess the impact on the existing system and project budget).
• 3. Change Implementation (Update the SRS, design, and code).

System modeling is the process of developing abstract models of a system, with each model presenting a different view or perspective of that system.

⇒10.1 System Perspectives

• External Perspective: Models the context or environment of the system.
• Interaction Perspective: Models the interactions between a system and its environment, or between the components of a system.
• Structural Perspective: Models the organization of a system or the structure of the data that is processed by the system.
• Behavioral Perspective: Models the dynamic behavior of the system and how it responds to events.

⇒10.2 Unified Modeling Language (UML)

UML is the standard graphical language for modeling object-oriented software. It provides various diagram types to cover all the perspectives mentioned above (Use Case Diagrams, Class Diagrams, Sequence Diagrams, State Diagrams).

Context models are used to illustrate the operational context of a system - they show what lies outside the system boundaries. Social and organizational concerns may affect the decision on where to position system boundaries.

⇒11.1 Context Diagrams

A simple architectural model that shows the system under development as a single black box in the center, surrounded by the other systems and environments it must interact with.

• Does not show how the system operates internally.
• Focuses entirely on identifying external boundaries and interfaces.
• Crucial for identifying security perimeters and required APIs.

⇒11.2 Process Context

Context models often include business process models (using UML Activity Diagrams or BPMN) to show how the system being developed is used in broader business processes.

Modeling user interaction is important as it helps to identify user requirements. Modeling system-to-system interaction highlights the communication problems that may arise.

⇒12.1 UML Sequence Diagrams

Sequence diagrams are used to model the interactions between the actors and the objects within a system in a chronological order.

• Lifelines: Represent the participants (objects or actors) in the interaction, shown as a dashed line dropping down from a box.
• Messages: Represented by arrows passing between lifelines. Time progresses from top to bottom.
• Activation Bars: Thin rectangles on lifelines indicating when an object is actively processing a message.

Sequence diagrams are excellent for documenting the specific sequence of API calls or function executions required to fulfill a single Use Case scenario.

Structural models display the organization of a system in terms of the components that make up that system and their relationships.

⇒13.1 UML Class Diagrams

Class diagrams are used to define the static structure of an object-oriented system.

• Classes: Represented as boxes with three compartments: Name, Attributes, and Operations (methods).
• Associations: Lines between classes showing that they interact.
• Multiplicity: Numbers on the ends of associations indicating how many objects participate (e.g., `1..*` means one to many).
• Generalization (Inheritance): Shown with an empty arrowhead pointing from the child class to the parent class.
• Aggregation/Composition: Shown with diamonds indicating 'whole/part' relationships.

During requirements, Class diagrams are often used as Domain Models to define the real-world concepts (like 'Patient', 'Doctor', 'Prescription') and how they relate, ignoring software implementation details.

Behavioral models are models of the dynamic behavior of a system as it is executing. They show what happens or what is supposed to happen when a system responds to a stimulus from its environment.

⇒14.1 Data-Driven vs Event-Driven

• Data-Driven: The system responds to arriving data (e.g., a batch processing system). Best modeled using Data Flow Diagrams (DFDs) or Activity Diagrams.
• Event-Driven: The system responds to external events (e.g., a microwave oven, a real-time game). Best modeled using State Diagrams.

⇒14.2 UML State Machine Diagrams

State diagrams show system states as nodes and events as arcs between these nodes. When an event occurs, the system moves from one state to another (a transition).

Example: A Microwave. States: `Waiting`, `Cooking`, `Paused`. Event 'Door Open' transitions the system from `Cooking` to `Paused`.

A Data Dictionary is a centralized repository of information about data such as meaning, relationships to other data, origin, usage, and format.

⇒15.1 Purpose in Requirements

As a system is modeled, many data entities are created. The data dictionary ensures that every term used in the SRS and the models has a single, unambiguous definition.

• Prevents naming conflicts (e.g., one analyst calling it `Client` and another calling it `Customer`).
• Defines data structures precisely (e.g., defining exactly what fields make up a `ShippingAddress`).
• Serves as the foundation for the database schema design later in the project.

⇒15.2 Contents

Typically contains: Data Item Name, Aliases, Description/Purpose, Type (Integer, String), Length, and Valid Values/Ranges.

A feasibility study is a short, focused study that aims to answer a number of questions to determine if the project should proceed.

⇒16.1 Types of Feasibility

• Technical Feasibility: Does the organization have the technology, tools, and expertise to build the system? Can it scale?
• Economic Feasibility (Cost/Benefit Analysis): Will the system provide business value greater than its cost? This involves calculating ROI (Return on Investment) and Payback Period.
• Operational Feasibility: Will the system actually be used if built? Does it align with current business processes, or will users resist the change?
• Schedule Feasibility: Can the system be built within the required timeframe to hit a market window?
• Legal/Ethical Feasibility: Does the system comply with laws (GDPR, HIPAA, copyrights)?

The outcome of this study is a document that recommends whether it is worth proceeding to the costly Requirements Elicitation phase.

⇒17.1 Quality Function Deployment (QFD)

QFD is a technique developed in Japan to translate user needs into technical requirements. It categorizes requirements into three types:

• Normal Requirements: Objectives the customer explicitly states. If present, the customer is satisfied.
• Expected Requirements: Implicit requirements so fundamental the customer assumes they are there (e.g., the system shouldn't crash). If missing, massive dissatisfaction.
• Exciting Requirements: Features the customer didn't ask for but are highly appreciated. They cause delight.

⇒17.2 Viewpoint-Oriented Elicitation

Recognizes that multiple perspectives exist. A bank ATM has requirements from the viewpoint of the Customer, the Bank Teller, the Security Administrator, and the Maintenance Engineer. This technique systematically collects requirements from every distinct viewpoint to ensure completeness.

When a system has complex business logic with many interacting conditions, natural language in an SRS becomes ambiguous and hard to follow. Decision tables and trees are used to formally model this logic.

⇒18.1 Decision Tables

A tabular representation of conditions and corresponding actions.

• Condition Stub: Lists all possible conditions.
• Action Stub: Lists all possible actions.
• Rules: The columns that map a specific combination of True/False conditions to specific actions.
• Excellent for ensuring that every possible permutation of conditions has been accounted for (completeness).

⇒18.2 Decision Trees

A graphical representation of a decision table. It uses a tree structure where internal nodes represent conditions, branches represent outcomes (True/False), and leaf nodes represent the final action. Much easier for non-technical stakeholders to read than a table.

In systems where failure means loss of life or massive financial disaster (safety-critical systems), natural language is too imprecise. Formal specifications are used instead.

⇒19.1 What are Formal Specifications?

They are mathematical models of a system based on set theory, logic, and algebra (e.g., Z notation, B method).

• They allow the software engineer to mathematically prove that the system design meets the requirements.
• They eliminate ambiguity perfectly.
• They uncover contradictions in the requirements phase that would otherwise be found much later.

⇒19.2 Drawbacks

They are extremely difficult to write and read. Clients cannot understand them, meaning they cannot validate if the mathematical model represents what they actually want. They are also incredibly time-consuming and expensive to produce.

Agile methodologies reject the idea of creating a massive, comprehensive SRS document upfront.

⇒20.1 User Stories

In Agile, requirements are captured as User Stories, typically written on index cards. The standard format is:
As a [role], I want to [action] so that [benefit].

• Card: The physical token representing the requirement.
• Conversation: The story is a placeholder for a conversation between the developers and the Product Owner that happens 'just in time' before coding.
• Confirmation: The acceptance criteria that define when the story is 'Done'.

⇒20.2 Epics and Backlog Refinement

Large requirements are called Epics. As an Epic moves closer to the top of the Product Backlog, it is progressively refined (broken down) into smaller, actionable User Stories during Backlog Refinement sessions. This ensures time isn't wasted detailing requirements that might change before they are built.