A Practical Guide to Transition from Waterfall to Agile


How to document the requirements


This article aims to provide a business analyst who is struggling with how to cross the over from the Waterfall way of documenting the requirements to the Agile way of doing so. Most importantly, it aims to show how most of the Waterfall elements of the requirements are still in the Agile User Stories, but are only presented in a much lighter manner.

1. Setting the scene

The transition from Waterfall to Agile is never easy – especially for a business analyst who must go through this journey. This document has come about because of this challenge and as an attempt to present a practical guide of how to effectively transition over as a business analyst, and where are these worlds connected. I do not believe that all that we learned as business analyst in the waterfall era are completely useless. What has changed in the Agile world is how we think about analysis, how we present the requirements to our business and our development and testing teams. It is by no means a comprehensive and one size fits all document. But it does provide a start and a guide for those who sometimes cannot make the connection.

Using one fictitious ‘User Story’ in the Agile section of this document, I provide concrete examples of how and when to present just enough information, while giving your audience sufficient understanding of what they need to bring the requirements to life.

2. In the Waterfall World

The Waterfall world is characterized by three distinct phases for analysis and design (with corresponding artifacts – the business requirements specification, functional requirements specification and systems/technical requirements specification).

Requirements Definition
Artifact Produced
Responsible Individual
‘What’ vs ‘How’ Definition
Data Requirements
Business Requirements

Process Requirements

  • Essential Processes
  • Decomposition Diagrams
  • Business Rules
Business Requirements Spec or Business Requirements Definition (BRS or BRD)
Business Analyst
‘What’ business wants
Data Definitions

Functional Requirements

  • User Interfaces (Screen prototypes, Report Layouts)

System Functionality

  • Use Case Descriptions
  • Workflows
Functional Requirements Specifications (FRS) or Functional Requirements Definition (FRD)
Business Analyst
‘How’ the solution will be delivered

Database Design

Technical Requirements
Software Design
Systems Requirements Specification (SRS) or Technical Requirements Specification (TRS)
Systems Analyst
‘How’ the solution will be delivered from a system perspective

a. Typical Content of Templates (BRS, FRS and SRS)

Project Scope
Design Area Scope (Impacted Systems)
Hardware descriptions
Statement of Purpose
System Functionality
Software descriptions
Database definition
Data Definitions
Design Flows
Quality Attributes (validations of data)
Program specification
Stakeholder Matrix
User Classes (User permissions)
External interface requirements (API’s, etc)
User Interfaces (Wireframes, mock-ups, etc)
Technical constraints
High-level business processes
Performance Standards (non- functional)
Technical standards
External interactions (context diagram)
Security Requirements (non-functional)
Business Processes/activities
Report Requirements (fields, layout, frequency)
Business Requirements
Business Rules
Data Requirements (Data/information needs)

3. In the Agile World

a. Kicking off the project (Sprint Zero)

This is what we would normally refer to as a Project Kick-off session in the Waterfall world and would typically be facilitated by a Project Manager. In the Agile word, nothing is stopping you, as business analyst to facilitate this session. Granted, a Scrum Master would facilitate it – but you will still be expected to provide input. These are some of the focus areas of this session.

  • Project Scope/Project Concept/Epic
  • Statement of Purpose
  • Objectives
  • Risks
  • Problems/opportunities
  • Stakeholder Matrix

Although I give an example of a Context Diagram in the next section of this document, but starting to develop this diagram quite early will help with two aspects (as a way of being better prepared for the session):

  • Project Scope (in/out) – even in the Agile world, we still need to agree on what is in scope (this is even more important to help facilitate other key conversations further down the line in the project, e.g. number of sprints, etc)
  • Stakeholder Matrix (because it easy to identify impacted entities using the Context Diagram)

b. The User Story Specification

There are several templates of User Stories, which makes it difficult to say what is the standard. However, there are common elements that can be listed that make up can be included in a User Story Specification Document:

  1. Keep it simple – you can use text and bullet points to the body of your user story and the acceptance criteria
  2. Gherkin framework – you can use text for the acceptance criteria
  3. Gherkin framework – you can use a table for the acceptance criteria
  4. Workflow, Flowchart, or other models, e.g. screen mockup, state diagram, domain model, etc. (as attachments to your user story)

Acknowledgement: Points 1 – 4 are adapted from Ronak Sanghavi’s BA Summit 2019 presentation ‘Crafting Effective User Stories)


The format of a User Story is as follows:

  • As a <user identity>, I want <desired feature> so that I can <achieve a goal>
    As a customer I want to be able to access online banking so that I can apply for a personal loan.

The acceptance criteria is:

  • a boundary of a user story, it states what must be true in order for a story to be confirmed that it is working as intended
  • a validation that the business rules are implemented and working correctly
Artifact Element
Section on the User Story Specification
External interactions
Context Diagram
Context Diagram
High Level Requirement(s)
Customers should be able apply for a personal loan on our online banking platform
User Story Title
As a customer I want access to online banking so that I can apply for a personal loan.

Business Requirements
Data Requirements
Data Definition
Business Rules

A customer should be able to capture personal details

  • Name
  • Surname
  • Id number
  • Company Name
  • Occupation
  • Income
  • Total Expenses
  • Employment Type
  • Salary Frequency
Acceptance Criteria
  • Customer Name is accepted if it is characters only (min 2, max 50).
  • Customer Name is not accepted if it is numeric or alphanumeric.
  • Customer Surname is accepted if it is characters only (min 2, max 60),
  • Customer Surname is not accepted if it is numeric or alphanumeric
  • Customer Id is accepted if it is numeric and passes the modulus check
  • Customer Id is not accepted if it shorter than 13 digits
  • Customer Id is not accepted if it has characters (A-Z)
  • Company Name can be numeric, alphanumeric or characters only.
  • Occupation is not accepted if is numerics only.
  • Occupation is not accepted if it shorter than 2 characters.
  • Income is not accepted if it is characters
  • Total Expenses is accepted if it numeric
  • If Total Expenses is greater than Income, display to Error Message 1, Mockup 1 (Attachments)
Process Requirements
Process Decomposition Diagram
Process Decomposition Diagram
Functional Requirements

User Interfaces

  • Mockup Screens,
  • Wireframes,



UI/UX Designs

  • Screen Mockups,
  • Wireframes,
  • Hand-drawn screen designs


Functional Requirements

Use Cases

  • Calculate affordability
  • Error Messages
Acceptance Criteria

System Flowchart (Calculate affordability)

  • Error Messages
  • Confirmation Messages


c. Test Acceptance Criteria

[List pre-conditions for acceptance criteria]

  • The home page for the <name of the finance institution> must be successfully presented to the customer
  • The ‘Apply for Personal Loan’ button/option must be successfully presented to the customer
1 Given

[That the user is at a certain point in the system]
The customer has successfully captured his/her name


[The user does something]
applying for the personal loan


[The action will provide a specific result]
the cursor must move to the next field

Number Description
2 Given [That the user is at a certain point in the system] The customer has not successfully captured his/her name
When [The user does something] applying for the personal loan
Then [The action will provide a specific result] the system must display the following error message ‘The name cannot contain numbers’

4. Diagrams

a. Context Diagram

b. AS-IS Process Decomposition Diagram
NB: This is not a system flowchart, but a business process decomposition diagram

c. TO-BE Process Decomposition Diagram
The new functionality that is required (Loan Application via Online Banking) is represented by the red box – which is the difference between the two business processes)

d. Screens (For UI Design)
Working with your UI/UX team, it is advisable that you provide any additional information relating to the fields that are required to bring your user story to life.

Field Name
Type of Field
Provide a list of the field names and buttons that you require for your user story For example, is this an edit box, a check box, a radio button, a drop down or a button
  • Any specific instruction linked to the field (e.g. is it a mandatory field or optional).
  • Provide the LOV (list of values in this section) if the field is a dropdown


e. Supporting and Referenced Documentation

Insert any document that you think might be relevant and be used as further reading to give more context to your user story

Embedded Document or Link
What is the name of the document
What is the document about
Embed the document here to make it easy for the reader to access it.

Author: Edward Ngubane, Head of Business Analysis, DVT

Edward Ngubane, the current Head of Business Analysis at DVT, started his career as a mathematics teacher at Senaoane Sec School in Soweto. He has been in the IT industry for almost 20 years, and worked for the following companies: Telkom SA, Investec, BMW Financial Services, Wesbank and FNB (Online Banking and eWallet Solutions). He has held numerous positions, viz:- Systems Developer, Systems Analyst, Business Analyst, Product Development Manager, Business Analyst Manager, Head of PMO, Practice Lead (Business Analysis and Architecture), Practice Manager.

He has setup and ran BA CoP’s (Community of Practice), developed and mentored a number of business analysts and published papers on the business analysis discipline. Over the years he has received numerous awards, and is passionate about the business analysis domain.

He holds five degrees, two of which are at the Masters level – the M.Ed (Maths Education) and the MBA (Cum Laude) – both from the University of the Witwatersrand. The title of his dissertation for his M.Ed was ‘What are links between a teacher’s views of mathematics and his/her classroom practices’. And the title for his MBA dissertation was ‘Managing IT Knowledge workers within South African Financial Industry’.

He is currently doing his PhD (part-time) at the University of the Witwatersrand, and is a recipient of a Post Graduate Merit Award. His thesis is on the ‘The development and sustainability of SMME’s through Cloud Computing in South Africa’. He is the former Secretary and Treasurer of the IIBA-SA, and is currently the President of the same organisation.

Contact details:
Edward Mzwandile Ngubane
DVT (https://dvt.co.za/))
Head of Business Analysis : Gauteng, South Africa
Business Enablement Division
Mobile +27 (82) 851 3638
[email protected]

Like this article:
  61 members liked this article


Anthony Constantinou posted on Saturday, May 30, 2020 5:41 AM
This is very informational. I like the approach. 5 Stars from Anthony Constantinou
Anthony Constantinou CEO CWM FX
Edward Mzwandile Ngubane posted on Tuesday, June 23, 2020 2:42 PM
Thank you so much @Anthony Constantinou. Your feedback is highly appreciated
Only registered users may post comments.



Copyright 2006-2024 by Modern Analyst Media LLC