through an improved understanding of the difference between high-level requirements (HLRs) and detailed requirements (DTRs).
The Trips-R-You case study is an addendum to that series, offering end-to-end examples of requirements documented using spreadsheet-based templates.
In IIBA® BABOK® V3 terminology, end-to-end means from Business Requirements to Stakeholder Requirements to Solution and Transition Requirements. Both the original series and the case study use the more traditional business terms Goal, HLR, and DTR. Also both only address functional requirements within the context of a project chartered to deliver an IT-based solution.
NOTE: A business may choose to organize their IT solution-delivery resources following Agile principles. But if the delivery of those solutions are managed by a project manager, or the Agile teams do not include a ‘real’ product owner – able and available to prioritize and refine user stories, then requirements still need to be documented and managed.
The Case Study
The case study involves a fictitious organisation — the Trips-R-You Travel Agency. It deals primarily with the requirements phase of an equally fictitious project, established to deliver a web-based customer self-service flight booking capability — commonly referred to as an Airline Reservation System.
The case study is divided into three sections, based on the three levels of requirements. The first section introduces the organization and a problem it faces. A goal is set that is intended to eliminate the problem, and a business case is commissioned to examine potential solutions.
The second section sees a project initiated to deliver the solution recommended by the business case. That project’s scope is shown, and how it leads to high-level requirements for the project.
The third section takes five HLRs to the detail level – one HLR involving each of the primary capability types a business information system is able to support:
- User Interface (UI)
- Data Import
- Data Export
- Automated Function
To support capturing the details involved in each of the above capability types, type-specific spreadsheet-based templates are utilized.
The third section also discusses and uses a Data Dictionary template. As the detail for a given HLR is discussed, the data-specific business needs involved are captured using this template. Once captured, those data-specific details are available for referencing in the other templates when those needs come up again, as they will, during discussions involving other HLRs.
NOTE: The Data Dictionary template incorporates the concepts presented in my 2018 “Well-defined Data” series.
Detailed Requirements vs Detailed Requirement Statements
It’s natural (and correct) to assume that for every HLR, there will be some number of DTRs. But what, exactly, should a detailed requirement look like? A formal requirement statement is expected to be a single sentence that includes the word ‘shall’ (rather than a term implying a priority such as ‘must’ or ‘should’). More typically, to accommodate detail, a textual requirement statement involves a number of sentences or paragraphs.
Requirement documentation techniques that make use of ‘fully dressed’ UML use cases describe an Actor interacting with ‘the system’ performing a given business activity. That description includes the individual steps within the activity, organized into different flows — one main flow and any number of alternate and/or exception flows. The step description includes names of individual fields and ‘controls’ (e.g. buttons) involved. The requirements documentation technique may treat each flow or each step within the use case as an individual DTR, or treat the entire use case as a single DTR.
The spreadsheet-based templates used by the Trips-R-You case study uniquely identify individual rows, each representing a detailed requirement (but not in ‘statement’ form). Three separate worksheets (tabs) are used to capture different categories of detailed requirement. Those three categories address:
- The capability’s operation – E.g. who needs it, when.
- An Individual element – E.g. a field, control, or step within an automated function.
- An Element Grouping – E.g. an area on a screen or report (see mock-up below), a record being imported or exported.
Tabular format allows for separate columns to represent different types of detail (i.e. characteristics) applicable to a given item. E.g. for an individual field element within a report area, characteristics identifying the font to be used and whether the field is to be justified left, right, or centered. The templates also support visual representations of the detailed requirements, such as screen or report mock-ups (see example below).
Because all of the details for a ‘unit of delivery’ (a specific UI, report, etc.) are captured in an individual spreadsheet file, those DTRs can be represented by a single ‘formal’ DTR statement (similar to a whole use case being treated as a single DTR). The following is an example from the case study of one of the HLR statements for a report, and its corresponding single formal DTR statement representing the template-based DTRs for that report:
REQ008 (HLR) - A customer shall be able to access and print the booking confirmation details.
REQ015 (DTR) - The system shall be able to produce a Booking Confirmation report for a specific Booking - as specified in DR015 - Self-service Booking Confirmation Report v1.0.
The template-based DTRs for this report consisted of the following:
# of Rows
The spreadsheet file also included the following mock-up, visually representing the six Report Areas and the Elements contained in each:
Individual Statements, Templates, or a Requirements Management Tool?
Requirements have a reputation for taking too long to document. They have probably earned that reputation from projects where: Requirements were ‘hand-crafted’ requirement statements; HLR statements were allowed to include too much detail; And DLR textual statements were written that included varying combinations of details about fields and/or field characteristics.
Keeping HLRs to the capability type-specific level (i.e. specific UI, report, etc.) is intended to avoid time wasted at this stage of requirements elicitation. Using capability type-specific templates is intended to save time by representing and providing space for capturing values for the specific types of details that need to be addressed for each capability type and category.
NOTE: The templates used in the Trips-R-You case study represent an amalgamation of detailed requirement types and characteristics based on my years of experience as a business analyst working in project teams delivering IT-based solutions. That experience included working for software package vendors, for organizations acquiring software packages, and for organizations outsourcing parts of a solution.
Better than spreadsheet-based templates, where affordable, would be a commercially-available requirements management (RM) or application lifecycle management (ALM) tool that supports the requirements-related concepts presented in the Trips-R-You case study.
The Trips-R-You Case Study as a Tool Benchmark
In addition to being an aid to understanding concepts related to HLRs and DTRs, it was hoped that the Trips-R-You case study would serve as a benchmark utilized by RM and ALM tool vendors. While their tools would not be expected to support all of the concepts out of the box, most tools currently on the market offer some degree of configuration. Any organization looking to acquire a commercially-available tool to support the requirements phase of IT-based projects might ask their candidate tool vendors to demonstrate their tool’s ability to support this case study.
NOTE: Any tool vendor that believes their tool to be capable of supporting the “Requirements in Context” concepts represented in the Trips-R-You case study is welcome to contact me for assistance with the benchmarking exercise.