NOTE: The Requirements-Friendly Data Dictionary 2.0 is a free, downloadable spreadsheet-based template. It is based on the development of a custom extension to provide data dictionary capabilities in the Modern Requirements4DevOps requirements management tool.
This article describes using a Requirements-Friendly Data Dictionary (RFDD) as an alternative to representing a software solution’s data-related requirements as User Stories, Use Cases, or traditional Waterfall Requirement statements. Any of these forms can still be used to document the solution’s functional requirements. An RFDD spreadsheet-based template or extended requirements management tool (RMT) provides a structured format that supports a business analyst documenting required Record and Field details while eliciting functional requirements.
This article discusses:
- Benefits of a Requirements-Friendly Data Dictionary
- What Makes a Data Dictionary Requirements-Friendly
- Populating a Requirements-Friendly Data Dictionary
- Next Steps
NOTE to current users of the RFDD Version 1.0 template – the 2.0 template is available now from the original 1.0 template location. The original 1.0 template populated with examples from the Trips-R-You Case Study has also been updated using the 2.0 template and is downloadable from its original location.
Benefits of a Requirements-Friendly Data Dictionary
Separating system-managed-data requirements from functional requirements using an RFDD provides the following benefits:
- Fewer, more consistent Functional Requirements
- Reusable, more complete Data Requirements
Fewer, More Consistent Functional Requirements
Consider the following two examples of data-related needs for a software solution that would typically be represented as individual user stories, requirement statements, or as details in a use case:
- Customer records need to include a unique identifier.
- A Purchase Order must have at least one Line Item.
Example 1
The need for Customer records to be uniquely identified can be represented in an RFDD by a CUSTOMER Record entry and a Number Field entry.
The RFDD field property Record Identification offers selectable options to describe the field’s role (if any) in identifying the record it’s contained in. Available pop-up help text in the form of an elicitation question is available for each property. That text includes either one or more example response or, as seen in this example, a property’s selectable options.
Example 2
A Purchase Order having at least one Line Item can be represented in an RFDD with Record entries for Purchase Order and PO Line Item, plus a Field entry Line Items for the Purchase Order record.
For fields involving related records, the Field entry includes field-type-specific properties including one to explicitly identify the related record.
Examples 1 & 2 are both data-related requirements for a given software solution. Using an RFDD to document data-specific needs establishes record and field terms as part of the vocabulary of the functional requirements. Those terms should be used consistently in the solution’s functional requirements.
Meanwhile, having documented those data-specific needs in the solution’s RFDD, the need for two functional requirements (in whatever form) is eliminated.
Reusable, More Complete Data Requirements
Like a Glossary in a document, an RFDD establishes a single source of Record and Field definitions that can be referenced (i.e. reused) by business analysts eliciting a software solution’s functional requirements.
The RFDD 2.0 template (or similarly extended requirements management tool) promotes completeness of data-related requirements by providing Record and Field-specific Properties like those presented in the examples above.
What Makes a Data Dictionary Requirements-Friendly
What makes a data dictionary Requirements-Friendly are the following characteristics:
- Uses Stakeholder-Friendly Terminology
- Be a Byproduct of Functional Requirement Elicitation
- Have a Software Solution Scope
- Manage Each Entry Like a Functional Requirement
- Provide Property-Specific Help
- Support Where-Used Linking
Uses Stakeholder-Friendly Terminology
It’s difficult to imagine a subject matter expert (SME) involved in requirement elicitation who has never used a software application that involves system-managed data. And when they use any of these applications, they think and speak in terms of the application data as records and a record’s field values being displayed on screens and in reports.
Given the context of an RFDD is solution requirements, solution delivery stakeholders should understand the use of these commonly understood terms, instead of the traditional data modelling terms Entity and Attribute, is not intended to dictate solution storage design or implementation.
Be a Byproduct of Functional Requirement Elicitation
A software solution is a collection of functional capabilities. A capability that uses Records and Fields will be one of the following types:
- User Interface (UI) - creates, updates, references, and/or deletes data
- Report – references data
- Data Import - creates, updates, references, and/or deletes data
- Data Export – references data
- Automated Function - creates, updates, references, and/or deletes data
Eliciting functional requirements for a capability of one of the above types should identify the need for records and fields to be managed by a software solution. Part of verifying functional requirement completeness is that all data that needs to be available for reference has at least one source.
Part of verifying functional requirement correctness is that sourced data undergoes necessary validation and that derivable data follows the correct derivation steps – both identified during functional requirement elicitation.
Have a Software Solution Scope
The RFDD 2.0 template is not intended to be used to establish an organization-wide glossary of terms. Its scope should be the same as the functional requirements for capabilities that use a software solution’s system-managed data. Ideally those terms are used as labels in the system’s user interfaces and reports.
If the system imports or exports data in machine-readable form, the RFDD is only concerned with the named Records and Fields its system manages. Ideally another system that provides or receives the machine-readable data would have its own RFDD to represent its data vocabulary.
Manage Each Entry Like a Functional Requirement
An RFDD is a structured way to document the system-managed data requirements used by a software solution’s functional requirements. That structure involves individually named entries with a defined set of properties to contain details of each entry.
As seen in Examples 1 and 2 above, data-related details could be documented in a functional requirement form. When they are documented using an RFDD, each entry should be:
- Uniquely Identified
- Assigned a Priority
- Follow a Requirements Management Process
RFDD 2.0 includes [unique] ID#, Priority, and Status properties for both Record and Field entries to support this.
Provide Property-Specific Help
The structure of a functional requirement in any of the three forms is simplistic. Each consists of:
- Who Wants a Functional Capability – a type of user or actor
- What Capability Do They Want – a system function
- Why Do They Want It – the value the capability provides (user stories only)
RFDD 2.0 structures system-managed data details as Properties of an individually named Record or Field. Each property is there to document a specific aspect of the entry. To assist both the BA and the SME expected to provide the entry-specific detail, each property should offer help text.
In RFDD 2.0 this help is in the form of a property-specific elicitation question plus either example responses or, where applicable, selectable responses.
Help text is available for each Record and Field Property in its column header. A “pop-up” note (see Example 1 screen shot above). That same Record and Field property help text is listed in a separate “Property Descriptions” template worksheet.
Support Where-Used Linking
A fundamental link supported by RFDD 2.0 is from each Field to the Record it is contained in. There are field-type specific properties that provide linking to other RFDD entries. Example 2 above showed a field involving related data linking explicitly to its related record.
If a Requirements Management Tool (RMT) is available that can be extended to support the RFDD 2.0 Record and Field linking properties that tool’s Where-Used capabilities should support this.
NOTE: RFDD 2.0’s support for “Where-Used” linking to Functional Requirements is outside the scope of this article. However, support for this is included in the downloadable template, along with linking supporting requirements-related Stakeholder Management.
Populating a Requirements-Friendly Data Dictionary
An RFDD is populated in conjunction with eliciting functional requirements for a software solution. Business Analysts depend on subject matter experts (SMEs) for the content of functional requirements. Because SMEs have ‘day jobs’, their availability is limited. During an effort to deliver a given software solution the BA may only have three opportunities to access SMEs:
- Eliciting High-Level Functional Requirements
- Eliciting a Functional Requirement’s Detail
- Reviewing Overall Functional Requirement Completeness and Correctness
During these opportunities the terms a SME mentions that represent system-managed data should either be confirmed to be existing RFDD entries or be noted as entries to be added - along with any property-specific details.
Eliciting High-Level Functional Requirements
A business analyst should keep the following in mind when eliciting high-level functional requirements involving system-managed data:
- The functional capability will be one of the five fundamental types (e.g. UI, Report)
- The data will typically involve a primary-type record.
- The capability’s data-related actions will be some combination of Read, Update, Reference, Delete.
The most efficient use of this SME opportunity is keeping elicitation at the record level. Getting into the detail of other record types or individual fields should be avoided. Doing this makes it clear that a subsequent opportunity will be necessary to address those details.
The result is primary Records added to the RFDD (name only) and available to reference (re-use) when eliciting functional requirement detail.
Eliciting a Functional Requirement’s Detail
Given a high-level functional requirement involving one of the fundamental capability types focusing on a primary record, the follow-on elicitation addresses the capability functional detail operating on the data. The business analyst can use appropriate techniques for addressing field-level detail, such as screen or report mock-ups or activity diagrams.
Details identified for a given functional capability that can result in the RFDD being populated include:
- The primary record’s fields and their properties
- Secondary records related to the primary record, their fields and properties
- Records referenced during the activity, their fields and properties
It’s appropriate for elicitation functional capability detail that involves adding a record address field-specific validation criteria. Elicitation of detail that involves referencing a derivable field should address its derivation.
Overall Review of Requirements
Given a software solution that will involve multiple functional capabilities implemented together, there should be an opportunity for the SMEs involved in those requirements to review them for overall completeness and correctness. This opportunity should encompass reviewing RFDD entry content.
For capabilities involving system-managed data completeness means that every referenced field has either an input source (e.g. UI or Import) or, if derivable, the fields it requires to perform the derivation all have sources.
Conversely, any Record or Field that is not involved in one or more functional capabilities or value derivations should be considered out of scope for the current solution (e.g. Priority “Won’t Have”).
Next Steps
A single article is unlikely to be sufficient to change the way you, or your organization, documents the requirements for a software solution’s system-managed data. But if the benefits, requirements-friendliness, and/or useability of an RFDD has you intrigued by the possibility, the following steps are recommended:
- Check out the RFDD Property-Specific Help Text – download the RFDD 2.0 template. The RFDD Record and Field Properties are represented as columns in the Records and Fields worksheets. The header of each column includes the pop-up help text described above. There is a separate worksheet that lists these properties and that same help text. As you review each question, consider if the requirements for a software solution using a given record or field is complete without a documented SME response.
For an example of a fully-populated RFDD 2.0 template based on the Trips-R-You Case Study see Record & Field Data Requirement Detail Examples.
- Second Opinion – If sufficiently convinced of the benefits of an RFDD, share this article with one or more BAs in your organization to get their opinion. Ideally, they will be interested enough to take one or more of these recommended steps.
- Existing Requirements Comparison – Given two or more BAs showing interest, test the RFDD 2.0 template as an alternate documentation form to an existing set of functional requirements. Find an example in your organization and see how many of those requirements would have been unnecessary had their detail been documented as RFDD entries.
- Pilot Project – Use the RFDD 2.0 template in a pilot project along with whichever functional requirement form normally used. If an extendable requirements management tool is available, the Record and Field worksheet columns in the RFDD 2.0 template should be sufficient to guide creating an RFDD extension.
NOTE: You are welcome to contact me with questions related to steps 3 or 4, for help extending an RMT, or with suggestions for additional Record or Field properties not currently included in RFDD 2.0.
Author: Dan Tasker, Independent Consultant, Author, Mentor
Dan is the author of over 30 requirements-related articles and other resources. His 50+ 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 requirements for information system solutions and helping business analysts produce them. He can be contacted at [email protected].
