Requirements In Context – The Series

Articles and Posts Nov 07, 2020 4 mins 9690 Views 0 Comments 1 Likes

The primary objective of the Requirements In Context series is to help business analysts improve their elicitation and documentation of requirements. It does this by providing a clear distinction between high-level and detailed requirements and, for detailed requirements, offering spreadsheet-based templates to guide the capture of details as an alternative to individual textual statements. A set of end-to-end examples accompanies the series, presented as a pseudo case study – The Trips-R-You Web-based Flight Reservation System.

Part 1 - Just Know it! discusses the importance of contexts. It identifies “functional requirements for business information systems” as the context for requirements covered by the series. A version of the classic 1973 “Swings” cartoon is presented to illustrate problems of representing business needs and producing a reasonable solution.

The fact that versions of this cartoon are still seen today is a good indication that requirements are still a problem.

Part 2 - The Functional View from 10,000 feet presents a generic model of functions applicable to any organization. Each of these functions acts as a context for the next functional level - Business Processes. These in turn act as a context for functions at a third level - Business Activities. An example of these levels of functionality is presented based on the SAP enterprise resource planning (ERP) system.

Part 3 – Scope = High-Level Requirements looks at scoping a project that involves an information system as part of the solution to be delivered. An example is presented of a use case context diagram representing the activities that are in scope for support by ‘the system’. Scope statements addressing functional capabilities within the system boundary are shown to lead to high-level requirements (HLRs).

Part 4 – Keeping High-Level Requirements High Level introduces five fundamental capability types that can be provided by an information system:

User Interfaces (UIs)

Reports

Data Imports

Data Exports

Automated Functions (e.g. batch jobs)

A properly high-level HLR identifies a need for a capability of one of these types (e.g. a UI supporting a specific business activity). The set of HLRs represents the capabilities to be delivered by a given project. Each HLR then acts as the context for detailed discussions (i.e. elicitation) about a specific capability. Details about a given capability (e.g. what fields are involved) are left for detailed requirements discussions involving stakeholders and subject matter experts.

Part 5 – Managing Data-Specific Business Needs Using a Data Dictionary is an ongoing BA activity during detailed requirements discussions. Details about any data ‘field’ involved in a given capability need to be understood (e.g. validation criteria). The first time a given field is identified as being needed its details should be captured (i.e. in a data dictionary). Details about the record the field is associated with (another context) should also be captured. Having done this, when the field or record is needed in other capabilities those details can simply be referenced rather than captured redundantly for each capability it is involved in.

Associated with the Part 5 article is a template for a data dictionary that shows what properties are applicable to records and to fields of different types (e.g. quantity fields, date fields). The template includes examples based on the case study.

Part 6 – Detailed Requirements for User Interfaces and Reports discusses the two capability types that involve data recognizable by humans. The data needs to be presented in ‘useable’ form and to include labels that give meaning to the values being displayed and/or captured. Mock-ups of screens or reports are considered to be critical to detailed discussions.

Even the simplest screen or report consists of a number of fields contained within a single area (i.e. one context). But for more complex capabilities, the mock-ups involve a number of areas, potentially including areas within other areas (e.g. a table within a screen). Each area acts as a context for the fields it contains. Details about each area and field contained need to be captured before requirements are complete. Spreadsheet-based templates specific to each of the capability types are offered that ‘structure’ the details rather than attempting to describe them in detailed text-form requirement ‘statements’.

Associated with the article are examples of a complex UI and report from the case study with their details captured using the corresponding template. Those examples include references to fields documented in the example data dictionary template.

Part 7 – Detailed Requirements for Data Importing and Exporting is similar to Part 6 but addresses two different capability types. Data imports and exports involve machine-readable data. Instead of areas, the fields being imported or exported exist within Record contexts. Again, a simple capability will involve a single record type. But more complex capabilities can involve multiple record types, possibly organized in a hierarchical structure (e.g. an order record as the parent of a number of child line-item records).

From a requirements perspective, the detailed discussions are about what fields (within records) are expected to be involved. An import capability identifies fields available for entry into the system in machine-readable form from a given source. An export capability identifies fields available within the system that are needed in machine-readable form by another system (capable of reading the file). Technical details about the overall record file or specific positions or formats of fields are a design rather than a detailed-requirement issue.

An example of details for data import and export from the case study are discussed. Again the details are shown captured using capability type-specific spreadsheet templates as opposed to any form of textual requirement statement. Fields involved are again linked to their detailed properties recorded using the data dictionary template.

Part 8 – Detailed Requirements for Automated Functionality discusses the fifth and final capability type. It’s similar to imports and exports, but the fields involved (again within record contexts) are all internal to the system. It uses data it has access to to create new data that the system is intended to manage.

What is different about an automated function is that it may involve steps that need to be described from a business perspective. Describing these steps represents the business requirement and subsequently supports design and testing of the delivered capability.

An activity such as periodically calculating and posting interest against bank savings accounts might only involve a few simple steps (repeated for each eligible account). But there can be complex functions that involve a number of steps, some that are part of a main path and others that are part of alternate or exception paths. Similar to areas and records being contexts for fields, paths would be a context for steps.

Accompanying the article is an example of details for a complex automated function from the case study. It includes record contexts for the fields that are available to the system as inputs and produced as part of the automated activity as outputs. It also includes steps describing the activity (represented visually as a UML Activity Diagram), within the context of a number of paths. All of this detail can be seen captured in structural form using an automated function capability type-specific template.

Part 9 – Tool Support for Managing Requirements [in Context] discusses extending commercially-available requirements management (RM) and application life cycle management (ALM) tools. These extensions are intended to capture the same ‘structured’ requirement-related details seen in the Trips-R-You case study spreadsheet-based templates. Examples of these extensions applied to three such tools are shown - each loaded with requirement-related details from the case study. The article is accompanied by the detailed meta-model that was used to create extensions in each of the three tools. This model is intended to be useable to create similar extensions in tools from other vendors.

By the conclusion of the series the reader is expected to have an increased understanding of:

The different contexts involved when eliciting and documenting requirements

The five fundamental information system capability types and be benefits of their use when eliciting high-level requirements

The benefits of capturing record- and field-specific details in a data dictionary

The advantage of capability-specific structuring of details required for a given capability rather than describing those details in textual requirement statements.