Tool Support for Managing Requirements [in Context]

Requirements In Context Part 9

This article discusses extensions to commercially-available requirements management (RM) and application lifecycle management (ALM) tools. These extensions are intended to support the concepts presented in the Requirements In Context (RIC) series of articles. End-to-end requirement examples based on those concepts can be seen in the Trips-R-You Web-based Flight Reservation System Case Study. That series focused on keeping high-level requirements high-level, and capturing requirement details in a structured manner rather than in textual detailed requirement statements. Spreadsheet-based templates were used in the case study to provide the structure for capturing requirements and their associated details.

The structure represented by the spreadsheet templates has been converted into a data model (i.e. a requirements meta-model). That model has been used to extend three currently-available RM/ALM tools — ReqView,⁽¹⁾ Visure Requirements ALM,⁽²⁾ and Enterprise Architect.⁽³⁾ The extensions to each tool were tested by populating them with requirement examples from the Trips-R-You case study.

Business analysts and/or organizations that see an advantage of applying RIC concepts to their requirements efforts can, ideally, apply these extensions to a tool they currently use. Or when looking to acquire a tool, they can factor in its ability to support the RIC extensions.

NOTE: RIC concepts apply only to functional requirements for capabilities provided by an information system.

Requirement in Context Concepts

All RM/ALM tools, ‘out of the box’, should support the concept of Requirement. The typical form of support involves a textual requirement Description, accompanied by properties such as Priority and Status. It’s left to users of the tool to manage the description content (and quality).

RIC includes the concept of Requirement, but introduces the additional concepts Operational Detail, Grouping Detail, and Element Detail, intended to give structure to requirement details. This reduces the content of a requirement statement to simply identifying a user role and naming a given capability (i.e. a user interface, report, data import, data export, or automated function). For example:

“A customer shall be able to request a copy of a booking confirmation report.”

Specific details of a required capability each have an appropriate place to be recorded within the structure provided by the RIC extensions. Detailed data-related needs that are not capability-specific are recorded within the structure provided by ‘data dictionary’ extensions — based on the RIC concepts Record and Field.

NOTE: The idea of requirement detail not being contained in the requirement statement itself is not new. A UML Use Case, ‘fully dressed’ with steps, acceptance criteria, and scenarios, has been used to represent the details of a user interacting with ‘the system’ to carry out a specific activity. RIC concepts provide additional structuring of element-level detail. This level of detail in a use case is typically included as part of the textual description of an individual step.

The following concept model represents RIC concepts that are the basis for RM/ALM tool extensions:

 

Examples of these concepts from the Trips-R-You case study are presented below, both in their original spreadsheet template form and as captured in an extended RM/ALM tool.

The following mock-up of the Trips-R-You Booking Confirmation report from the case study will be the basis for examples presented in this article:

Information System-based Capability Types

An information system is the combination of a database management system (DBMS) and some number of domain-specific capabilities provided through software. A business need that can be satisfied by an information system will be through one of the following five fundamental capability types:

• User Interface – a capability that provides on-line access, allowing users to reference and maintain information in the system.

• Report – a capability that provides a snapshot of information from the system available for user viewing off-line.

• Data Import – a capability that allows data available in machine-readable format to be captured by the system.

• Data Export – a capability that provides a snapshot of information from the system available, in machine-readable format, most typically for importing by another system.

• Automated Function – a capability that allows the system, using data available to it, to generate new data and/or update existing data.

The concept of Capability Type is fundamental to the RIC approach. It is used as a classification scheme for functional requirements (see next section).

Requirement Concept Extensions

RIC extends the concept of Requirement with a number of properties. One of these identifies its specific Capability Type. RIC uses the Requirement Type property to indicate if a [functional] requirement is high-level or detailed. A high-level requirement (HLR) represents a capability in scope within the context of an IT project (i.e. each specific UI, Report, etc.). The HLR in turn represents the context for one or more capability-specific detailed requirements (DTR).

Spreadsheet Template Requirements Example

Example of Requirements imported into Visure from an Excel document

Each DTR, having identified the capability it represents, acts as the context for the capability’s Operational Details and Grouping Details.

Operational Detail Concept Extensions

An operational detail for a given capability addresses what is needed for the implemented capability to perform in production. RIC includes a comprehensive set of questions specific to each of the five capability types (see examples below). These act as a checklist of operational details that a domain SME is expected to provide.

A capability’s operational details are actually non-functional. But because they are applicable to a specific functional capability it’s appropriate, from an RIC perspective, to manage them within that context, and in a structured way.

NOTE: The operational detail questions within the context of a specific capability are not intended as a replacement for traditional system-level non-functional requirements.

Spreadsheet Template Operational Details Example

Operational Detail Examples Using Enterprise Architect Extensions

NOTE: A complete list of RIC operational detail questions for each capability type is included with the RIC Tool Extension Meta-Model.

Grouping Detail Concept Extensions

The ultimate level of detail for a capability is the element level. RIC recognizes that individual elements for a given capability exist within the context of some business-meaningful grouping. The RIC concept Grouping Detail represents that context.

There are three categories of grouping detail:

• Data Grouping Detail – groups a number of element details similar to how an RIC data dictionary record groups a number of fields. The difference is that the rationale for this grouping of elements is capability-specific, where the grouping of fields within records has a different rationale, which is capability-independent. A capability-specific group of data elements may represent the input or output parameters for a capability, or import- or export-specific records. A capability can involve a number of different data groupings related in some way (e.g. a hierarchical structure). In such cases a diagram showing their relationships is recommended.

• Area Grouping Detail – groups a number of element details that make business sense ‘appearing together’ in a user interface or report. E.g. grouped on separate ‘process flow’ screens within a UI, columns of a table within a screen or report. A mockup of a UI or report capability is highly recommended. The mockup should include identifying each area grouping, allowing its corresponding entry within the tool to be recognized. 

• Process Grouping Detail – groups a sequence of ‘step’ elements that have a business-meaningful beginning and end. E.g. a ‘happy path’, an alternate path, or an exception path. For processes involving a number of groupings a visual representation such as a UML Activity diagram is recommended.

Spreadsheet Template Grouping Details Example

Grouping Detail Examples Using ReqView Extensions

 

Element Detail Concept Extension

At the bottom of the RIC requirement detail structure is Element Detail. RIC supports capturing details of the following four element types:

• Data Item – a data field needed by the capability, whether it’s managed by the information system, derived specifically for or by the capability, or participating in a capability-specific derivation.

• Label – text presented on a UI or report to identify a data item, or group of data items being displayed or to enhance usability. These text elements would typically be included in a mockup, but for requirement management purposes they should be individually captured as part of the RIC structured detail.

• Control – an item within a UI that triggers an action (e.g. a button, a navigation link). NOTE: The actual control-type involved is a design issue. From a requirement detail perspective the element is identified as having a ‘trigger’ role. A property of the control element allows for a description of the result of the action triggered.

• Step – one of the instructions within a complex automated function capability. An automated function capability that is complex enough to involve multiple steps should have each step managed as an element. While the primary detail for a step is its textual description, that text will be well positioned within the context of a capability requirement. Any reference to data within that description should be represented by an element detail in one of the data item’s Grouping Details within the context of that same requirement.

Within the RIC detail structure, every element detail instance is within the context of a business-meaningful grouping detail instance. And every group detail instance is within the context of a specific detailed requirement instance.

Spreadsheet Template Element Details Example

Element Detail Examples In Visure Requirements ALM

 

Data Dictionary Record and Field Concept Extensions

Many RM/ALM tools include a Glossary and/or Data Dictionary capability. RIC includes the concepts Record and Field intended to support defining capability-independent details about data that is expected to be managed by the information system. Each Field exists within the context of a Record.

NOTE: RIC uses the business-friendly terms record and field rather than IT-ish terms such as Class, Entity, and Attribute. It also takes the object-oriented view of Relationships – treating one direction of a relationship as an attribute of the class it originates from. In RIC terms - a field within a record. E.g. a “Customer” field within an “Order” record.

RIC tool extensions associate a number of properties as details of a record or a field. The property Field Type classifies each field as being one of seven types (e.g. Label, Quantity, Description). Some field properties are type independent (e.g. Mandatory, History Required). Other properties are type specific (e.g. fields of type Quantity have Precision and Unit of Measure). The RIC extension meta-model includes and describes each of these properties.

Spreadsheet Template Data Dictionary Example

Data Dictionary Record and Field Examples Using Enterprise Architect Extensions

 

Stakeholder

The concept of Stakeholder within RIC is analogous to the UML Use Case Actor concept, the Dataflow Diagram External Entity concept, and the process model Swim Lane concept. RIC utilizes this concept, adding or extending it to include user, source, and owner relationships to other RIC concepts (see RIC meta-model for details).

Spreadsheet Templates vs RM/ALM Tools

The Trips-R-You case study examples utilize spreadsheet-based templates to illustrate RIC concepts and structured details. There is one template for requirement statements, one for the data dictionary, and a type-specific template for each of the five capability types.

The capability-specific templates were designed to capture details for only one capability (of one of the five capability types). That means there would be one spreadsheet file for each UI, each report (etc.) in scope for a project. An RM/ALM tool captures all requirements and their details together for a single project. Some tools provide support for documenting multiple projects within a single file.

Spreadsheets allow for data in one worksheet to reference data in other worksheets. A referenced worksheet may be in the same spreadsheet file or in a separate file. For example, it was possible for an element detail in any of the capability-specific worksheets to reference its corresponding field within the data dictionary spreadsheet. But the opposite was not achieved (or even attempted). That is — for a given data dictionary field, what capability-specific element details involved it?

The ability to navigate defined relationships between items in either direction within an RM/ALM tool is a big advantage. The following illustrates using tool extension links to identify usage of fields within capabilities. This is possible by following links:

1. From each Record to the Fields it is the context for
2. From each Field involved in an Element Detail
3. From each Element Detail to the Grouping Detail that is the context for an Element Detail
4. From each Grouping Detail to the Detailed Requirement that is the context for the Grouping Detail.

Once this traceability has been defined, it can be applied to one Record, a filtered set of records, or all Records.

Where-Used Example Using ReqView Extension Links

NOTE: The ability of an RM/ALM tool to display or report on data maintained within or derived from extensions is outside the scope of RIC. Such capabilities should be discussed/confirmed with the tool vendor.

The RIC spreadsheet templates are available for use on an ‘as is’ basis. Their original purpose was to demonstrate capturing requirements and their details in a structured manner. They were never intended for ‘serious’ project work.

My personal recommendation would be to conduct an evaluation of commercially-available RM/ALM tools, including their ability to support RIC extensions.

Where To From Here?

This article has been about extending a commercially-available RM/ALM tool to capture and manage requirements and associated details in a structured form, rather than in textual statements. Three such tools have RIC extensions applied and can be tested on a free trial basis (see notes below). Accompanying this article is the RIC Tool Extension meta-model that was the basis for creating those extensions. This model is intended to be used as a guide to extending other RM/ALM tools that offer sufficient extension capabilities.

⁽¹⁾ ReqView Requirements Management Tool – Request an evaluation copy here and see a blog post specific to the RIC extensions here.

⁽²⁾ Visure Requirements ALM – Request an evaluation copy here and the Visure team will provide the project template upon request at [email protected]

⁽³⁾ Enterprise Architect – Request a trial edition here. Download the RIC extension from here (search this site for “RIC MDG Technology”).

---

Author: Dan Tasker

Dan is the author of over 30 requirements-related articles and other resources. His 45+ year career in Information Technology has involved organizations in a variety of industry sectors in the United States, Canada, Australia, and New Zealand. His business analysis experience includes projects involving in-house software development, software vendor solution development, and COTS software acquisition and implementation. He continues to be passionate about quality requirements and helping business analysts produce them. He can be contacted at [email protected].