Defining and Documenting User Requirements
Welcome to this study guide on Defining and Documenting User Requirements! If you are designing and building software, you might be tempted to jump straight into coding. However, coding without clear requirements is like trying to build a house without architectural blueprints. You might end up with a building that has five front doors and no roof!
In this chapter, you will learn how systems analysts and software developers discover what a client really needs, how to turn those needs into precise technical requirements, and how to document them clearly so that your development project succeeds.
Don't worry if this seems like a lot of theory at first — we will break down every single concept with simple everyday analogies and practical examples!
---1. What are User Requirements?
A requirement is a specific statement that describes what a software system must do or a quality standard it must meet. Requirements form the formal contract between the client (who pays for or uses the software) and the software developers.
Functional vs Non-Functional Requirements
In Software Systems Development, all requirements are divided into two main categories:
1. Functional Requirements (What the system does)
These describe the specific behaviours, tasks, inputs, processing, and outputs of the software.
Analogy: When buying a car, the functional requirements are that pressing the accelerator speeds up the car, pressing the brake stops it, and turning the steering wheel changes direction.
Software Examples:
• The system must allow a customer to log in using their email and password.
• The system must calculate sales tax (\(20\%\) VAT) and add it to the total basket price.
• The system must generate a PDF receipt and email it to the user upon checkout.
2. Non-Functional Requirements (How the system performs)
These describe the quality attributes, constraints, performance targets, and overall user experience of the system.
Analogy: For the car, non-functional requirements would be that it can reach \(0\text{ to }60\text{ mph}\) in under \(6\) seconds, has a \(5\)-star safety rating, and comes with heated seats.
Software Examples:
• Performance / Speed: The search query must return results in less than \(2\) seconds.
• Security: All passwords must be hashed and salted before storage, and communications must use SSL/TLS encryption.
• Usability / Accessibility: The user interface must comply with WCAG accessibility guidelines.
• Reliability / Availability: The system must achieve \(99.9\%\) uptime during normal business hours.
• Maintainability: The source code must be modular and documented so that future updates are straightforward.
Did you know? Building a system with perfect functional features that crashes under heavy load is a classic failure of non-functional requirements!
Key Takeaway: Functional = Actions and features. Non-Functional = Quality, performance, and constraints.
---2. Stakeholders: Who Are We Building For?
A stakeholder is any individual, group, or organisation that has a direct or indirect interest in the software system being developed.
Key Types of Stakeholders:
• End Users: The people who will interact directly with the software daily (e.g., checkout staff, bank clerks, customers). They care deeply about usability and efficiency.
• Clients / Business Owners: The individuals funding the project. They care about cost, return on investment, deadlines, and business goals.
• System Administrators & IT Staff: The technical team responsible for maintaining, backing up, and deploying the software. They care about security, scalability, and compatibility.
• Software Developers & Testers: The engineering team building and verifying the system. They need requirements to be unambiguous and testable.
Common Mistake to Avoid: Never design software only by consulting the business owner. If you do not consult the actual end users who complete daily tasks, the software may be clunky, inefficient, or rejected completely by staff!
---3. Fact-Finding Techniques (Requirements Gathering)
How do we find out what the stakeholders need? Analysts use four primary fact-finding techniques:
1. Interviews
A structured or semi-structured one-to-one conversation between the analyst and a stakeholder.
• Advantages: Allows deep questioning, open-ended discussion, and observation of non-verbal cues. Helps build rapport.
• Disadvantages: Very time-consuming, expensive to conduct across large organisations, and answers may be biased or inconsistent between interviewees.
2. Questionnaires / Surveys
Distributing a set of pre-written questions (multiple choice or short answer) to a large group of people.
• Advantages: Quick and cheap to gather data from hundreds of users; easy to aggregate data into statistics.
• Disadvantages: Questions can be misunderstood; lack of depth (no immediate follow-up questions); response rates can be very low.
3. Observation
The analyst watches staff perform their daily tasks in their normal working environment.
• Advantages: Shows what users actually do rather than what they say they do. Identifies hidden bottlenecks or manual workarounds.
• Disadvantages: The Hawthorne Effect (people change how they work when they know they are being watched); can be stressful for staff; takes significant time.
4. Document Analysis (Reviewing Existing Documentation)
Examining current paper forms, invoices, system manuals, spreadsheets, and error logs.
• Advantages: Provides concrete evidence of required data fields, workflows, and business rules.
• Disadvantages: Existing documents can be outdated, misleading, or fail to explain why certain steps are performed.
Key Takeaway: Use a combination of methods. A questionnaire can spot general trends, interviews explore details, and document analysis identifies exact data fields.
---4. Documenting User Requirements
Once requirements are gathered, they must be recorded in standard formats so developers and clients have a shared understanding.
1. Software Requirements Specification (SRS)
The SRS is the official comprehensive document that outlines everything the system must achieve. It contains the project scope, functional and non-functional requirements, data definitions, and interface designs. It acts as a legally binding contract between client and developer.
2. User Stories (Agile Approach)
In modern agile methodologies, requirements are often written as short, simple statements from the perspective of the user.
Standard User Story Template:
"As a [role], I want to [action], so that [benefit]."
Examples:
• "As a registered customer, I want to reset my password via email, so that I can regain access to my account if I forget my credentials."
• "As a warehouse manager, I want to filter stock by expiry date, so that we can sell older products before they spoil."
3. Use Cases and Use Case Diagrams
A Use Case describes a specific sequence of interactions between an external user (an Actor) and the system to accomplish a particular goal.
A Use Case Description usually includes:
• Actor: The person or system interacting with the process (e.g., Customer).
• Pre-condition: What must be true before the use case begins (e.g., Customer is logged in).
• Main Flow / Happy Path: The ideal step-by-step sequence of events.
• Alternative Flows: What happens if something goes wrong (e.g., Payment card declined).
• Post-condition: The state of the system after completion (e.g., Order saved to database, confirmation displayed).
4. Data Dictionaries
A Data Dictionary is a centralised document listing all data items used in the system, defining their data type, field length, validation rules, and purpose (e.g., `CustomerID`: Integer, Primary Key, Auto-increment).
---5. Validating and Prioritising Requirements
Not all requirements are equally urgent, and clients often request more features than their budget or timeline allows. Analysts must prioritise and check requirements for quality.
The MoSCoW Prioritisation Technique
A popular and practical framework for ranking requirements:
• M - Must Have: Critical, non-negotiable requirements. Without these, the system is fundamentally unusable and cannot be launched.
• S - Should Have: Important features that add significant value, but a temporary manual workaround exists if deadlines are tight.
• C - Could Have: Desirable "nice-to-have" enhancements that will only be included if extra time and budget permit.
• W - Won't Have (this time): Features agreed to be out of scope for the current release, but potentially planned for future versions.
Memory Trick: Remember M-S-C-W with the vowels 'o' added to make MoSCoW!
Characteristics of Good Requirements (The SMART Approach)
Every documented requirement should meet rigorous standards:
• Unambiguous: Clear and cannot be interpreted in more than one way.
• Testable / Verifiable: There must be a clear way to verify whether the requirement has been met.
Poor: "The website must load very fast." (What does 'very fast' mean?)
Good: "The homepage must render completely within \(1.5\) seconds over a standard 4G connection."
• Complete: Contains all necessary details without missing information.
• Consistent: Does not contradict other requirements in the specification.
• Traceable: Each requirement has a unique ID (e.g., `REQ-101`) so it can be tracked through design, coding, and testing.
Quick Review: Chapter Checklist
Before moving on, make sure you can answer these core questions:
1. Can you explain the difference between a functional and a non-functional requirement with two clear examples of each?
2. What are the pros and cons of interviews vs questionnaires when gathering data?
3. What is the standard template for writing an Agile User Story?
4. What do the letters in the MoSCoW prioritisation acronym stand for?
5. Why is a vague requirement like "The system should be user-friendly" considered poor practice in software engineering?