I measure the success of my 50+ year career in IT by the positive feedback I’ve received from colleagues, stakeholders, students, and readers. I started as a Cobol programmer, progressed to software analyst/designer, and for the last 30 years have performed the role of business analyst. Interspersed in those years I’ve shared what I’d learned through writing, teaching, presenting, and mentoring. This article discusses the top seven “Takeaway Points” from the over-30 BA resources I’ve produced related to requirements for information systems.
My top seven takeaway points are:
- Information Systems Have 5 Fundamental Functional Capability Types
- Information Systems Support Business Activities
- A Capability Has a LOT of Requirement Detail
- Data Requirements Are Reusable
- A Diagram Is Not a Picture
- A BA Should Talk Business Function but Think Business Data
Embedded in the discussion of each point are links to resources I’ve published. They offer further discussion, templates, and examples.
Requirement Form and Content
Requirements are a combination of form and content. The BA’s job is to elicit and document these in a form acceptable to both business and IT stakeholders. The original form was Shall Statements. When the Unified Modeling Language (UML) was introduced Use Cases became a popular form. More recently Agile introduced User Stories. These have become the form of choice for organizations able, or just hoping, to “be agile”.
The concepts of requirement Form and Content will be seen to play a role in the takeaway points discussed below.
Point 1 – Five Fundamental Capability Types
Several years ago, the Agile concept of “Unit of Delivery” led me to viewing information systems as having fundamental capability types. As part of preparing this article I did a web search for “software unit of delivery”. The response I got (attributed to the search engine’s AI) confirmed my understanding:
“… a discrete, manageable piece of software functionality that can be independently developed, tested, and delivered as part of a larger software system.”
Based on my years of experience as a BA involved with information system solutions, I’ve found there to be just five functional capability types:
User Interface (UI) – the capability for an on-line user to add, view, update, or request deletion of domain-specific data the system manages.
Report – the capability to format domain-specific data the system manages, making that information available for users off-line.
Data Import – the capability for the system to receive domain-specific data, available in machine-readable format, for the purpose of adding, updating, or deleting data the system manages.
Data Export – the capability for the system to format machine-readable domain-specific data it manages, making it available to other applications or systems for the purpose of adding, viewing, updating, or deleting data they manage.
Automated Function – the capability for the system to add, update, delete, or derive domain-specific data it manages, utilizing other data it manages or has access to.
Thus, within the context of information system solutions, I believe the definition of a unit of delivery becomes:
“… a specific UI, Report, Data Import, Export, or Automated Function that can be developed (or acquired), tested, and delivered as part of an information system.”
The Trips-R-You Web-Based Flight Booking Case Study describes a business analyst tasked with producing end-to-end functional requirements for an information system-based solution to a business problem. It provides examples of both high-level and detailed requirements (HLRs and DTRs) for each of these types.
NOTE: The article I wrote for ModernAnalyst.com that introduced the above capability types has been viewed more than 70,000 times. Not one reader has contacted me to suggest a change or addition to the five types.
Takeaway Point Takeaways
- Each capability of one of the five fundamental types represents a unit of delivery.
- Capability types of the five types support an information system sourcing, displaying, updating, generating, and delivering data.
Takeaway Action Recommendations
Given that an information system will be involved in the solution to a business problem or opportunity:
- Recognize that UIs, Data Imports, and Automated Functions are available options for getting data into the system or updating it.
- Recognize that UIs, Reports, and Data Exports are options for referencing system-managed data.
Point 2 - SMEs Have Day Jobs
Whenever I’ve been given the task of producing requirements for an information system solution my first question is always, “What’s the scope of the solution?” My second, equally-important question is, “Who are the subject matter experts (SMEs)?”
An SME must be both willing and able to take time away from their day job to provide requirement content. Signatories typically depend on SMEs to confirm that the documented requirements are complete and correct.
NOTE: All SMEs providing requirement content are stakeholders, but not all stakeholders involved in an information system-based solution are SMEs.
Keeping High-level Requirements High-level
A non-trivial problem that I’ve experienced often is that SMEs (and other stakeholders) invited to participate in HLR discussions don’t understand (or don’t care) about the difference between high-level and detailed requirements. They have been asked to take time away from their day job, and they see this as their one opportunity to “state their requirements”.
Allowing this to happen results in SME-time wasted discussing details that are meant to be addressed later. The second waste of everybody’s time, if those details are documented as HLRs, is everyone having to deal with a much longer list of HLRs (i.e. drafting, reviewing, signing-off).
The subsequent problem is that when it comes time to discuss DTRs, those same SMEs, believing that they’ve already “given their requirements”, resent being asked to take additional time from their day job.
NOTE: BAs are often tasked with documenting current and/or future state business processes as part of a requirements effort. It should be understood that SME time needed to provide business process content is in addition to time needed to provide requirement content.
To avoid these problems, I recommend making it clear to SMEs that the initial time they are contributing is intended to refine the initial project scope. The objective is to identify only the specific business activities that should be supported by UIs, Reports, etc. It should be made clear that their expertise will be needed at a later time to discuss details of the activities confirmed to be in-scope.
Takeaway Point Takeaways
- Lack of solution-domain-specific SMEs is a risk to a well-defined scope.
- Lack of capability-specific SMEs is a risk to its well-defined requirement detail.
- Non-SME stakeholders have a stake in the requirements. If participating in requirement content discussions, the questions they raise can be helpful, but non-expert contributions need to be managed.
- Requirement signatories don’t have requirements; they rely on delegated SMEs.
Takeaway Action Recommendation
- Treat SME availability as a precious resource that should be spent sparingly and wisely.
Point 3 - Information System Capabilities Support Business Activities
My perception of a Business Activity comes from an analogy I heard many years ago that was intended to describe the scope of a UML Use Case:
- An office worker picks up an item from their “In Basket”.
- Without any interruption they carry out the specific steps they have been trained to perform.
- Having achieved the goal of performing those steps they place the item in their “Out Basket”.
I view most business activities within the context of a business process. Swim lanes have labels similar to actor (role) names. All activity performed by that actor is contained within that swim lane.
There can be standalone business activities, such as entering a change of address or viewing a dashboard. Thanks to the internet — and cell phones — more and more standalone business activities can be performed by customer [actor] self-service.
UIs support individuals performing business activities. The other four capability types automate producing a report, entering data into the system, formatting data for other systems, or deriving new data based on available data.
Information System HLRs
I recommend that each business activity that is a candidate for support by an information system solution be represented by a high-level requirement. The HLR can be in the form of a Shall Statement, a named Use Case and Actor, or a User Story.
The content of that HLR should identify:
- The business activity to be supported
- The type of user benefiting from it (e.g. swim-lane role, use case actor)
- The capability type (UI, Report, etc.)
- The priority of that activity being supported in the system (e.g. Must, Should …)
If the intent is for the capabilities to be developed, either in house or outsourced, an initial estimate of the complexity of each capability should also be included (e.g. simple / medium / complex). HLRs with this content can also be used to evaluate commercial off the shelf (COTS) solutions.
Takeaway Point Takeaways
- Information system support for an in-scope business activity involves delivery of a capability of one of the five fundamental type.
- An HLR representing an in-scope business activity should be a single sentence.
- Individual activity fields or actions related to an in-scope business activity should be left to DTRs.
Takeaway Action Recommendations
- Treat HLRs as an SME-sourced wish list of in-scope solution capabilities.
Point 4 – Lots of Capability Requirement Detail
A primary reason I developed the Trips-R-You Web-Based Flight Booking Case Study was to provide the business analyst community with real-world examples demonstrating how much requirement detail there can be for each of the five information system capability types. Some of that detail was provided by a friend with over 20 years’ experience working as a travel agent. Other details were based on existing flight reservation web sites.
A secondary reason for the case study was to demonstrate the advantage of structuring information system capability detail. To that end five spreadsheet-based templates were developed - one for each capability type.
What structuring the capability-required detail offers over text-based requirement templates is:
“A place for everything, and everything in its place.”
The requirement detail for an information system capability includes:
- Identifying every data element involved in the business activity that the system is expected to manage.
- Identifying every action involved in the business activity that the system is expected to be able to perform.
The case study includes fully-detailed, real-life examples of structured functional-requirement content for each of the five capability types:
- User Interface – 101 data elements plus 15 action elements within 17 UI areas across 3 UI screens
- Report - 62 data elements within 6 report areas
- Data Import - 36 data elements from taken from 6 record types
- Data Export - 31 data elements populating 4 record types
NOTE: I’ve explored the possibility of capturing DTR content by extending commercially available requirements management or application lifecycle management tools (RMTs / ALMTs). That article includes details intended to support an organization that uses or acquires an extendable tool to carry out those extensions.
Structuring DTR Content
Having provided [structured] examples of the amount of detail involved in capabilities of each of the five capability types, the issue of acceptable requirement form needs to be considered. I have no illusions that BAs or organizations will abandon their current form(s) of documenting requirements to start using spreadsheet-based DTR templates. BAs will have to make-do documenting each in-scope capability’s detailed content using one or more Shall Statements, a “fully dressed” Use Case, or a User Story’s “acceptance criteria”.
While these forms remain appropriate for business stakeholders reviewing and signing-off DTRs, they are not the best form for stakeholders responsible for capability-specific unit of delivery design, development, testing, or user training.
Given the BA's familiarity with the content of DTRs in whichever current form, I believe it’s worth taking the time to structure each capability’s signed-off details using a template or extended RMT/ALMT.
Takeaway Point Takeaways
- There is a lot of capability-specific DTR content that the current detailed requirement forms will need to represent.
- BAs can provide value to capability-delivery stakeholders by structuring signed-off DTR content.
Takeaway Action Recommendations
- Recognize how much DTR content needs to be addressed and documented using an acceptable DTR form.
- Structure signed-off DTR content using a spreadsheet-based template or extended RMT/ALMT.
Point 5 – Data Requirements Are Reusable
Detailed requirements that describe information system solution records and fields are technically functional requirements. Ones like the following are commonly found mixed in with other DTRs:
“A customer must have a unique identifier.”
“A Purchase must identify at least one product.”
A recommended alternative to describing details of record types and fields as individual DTRs is to consider all such details as reusable Data Definitional Requirements (DDRs). It should be acceptable to stakeholders that record and field definitions be managed separately from other DTRs, rather than as individual requirement statements.
A glossary is a common mechanism used to define terms and acronyms that are used repeatedly in a given document. The information system equivalent of a glossary is a data dictionary (DD). Numerous examples of DD templates can be found on the web.
A Business-Friendly Data Dictionary
The Trips-R-You case study describes DDR content being structured within a business-friendly data dictionary. It provides examples of DDR content based on data elements identified in the five capability type examples. A separate article offers further discussions about business-friendly data dictionaries, compared to traditional DDs and to data models. A webinar focuses on the reusability of DDR content.
Based on my experience, I believe the characteristics that make a data dictionary business-friendly are:
- The terms record and field are used rather than data modelling or physical database terms such as “Entities and Attributes” or “Tables and Columns”.
- Record and Field entries use business terminology and have business-oriented descriptions.
- Field entries represent data expected to be managed by the system based on their involvement in multiple in-scope capabilities.
- Fields whose values are system-derived include the business rules that describe their derivation.
- Fields are independent of any specific database technology (e.g. do not require to be normalized to accommodate relational database management table structures).
- The Record Types and Field Types supported should aid BA elicitation of DDR content from SMEs (See Takeaway Point 7).
NOTE: For organizations that utilize a commercially available RMT or ALMT, it should be possible to extend that tool to capture DDR content.
A Single Information System Solution Data Capability Requirement
Given a business-friendly data dictionary containing the DDR content, that content can be represented in the form of a single Data Capability requirement. For example:
“The information system shall be able to maintain the record types and fields as defined in [business data dictionary version reference].”
The Unit of Delivery of the above requirement is the implementation of the solution information system’s domain-specific data structures. When the solution involves a commercially-available database management system (DBMS), the deliverable is a DBMS-vendor-specific database schema.
Takeaway Point Takeaways
- Record and Field definitional details should be documented as DDRs, rather than as DTRs.
- DD field entries should be based on Data Elements being involved in multiple in-scope capabilities.
- The DDR content should be represented to stakeholders as a glossary representing the solution-managed records and fields intended to be signed-off in conjunction with DTR content.
Takeaway Action Recommendations
- Introduce stakeholders to the concept of DDR content performing the role of a glossary of the reusable data managed by the information system solution
- Provide stakeholders access to structured DDR content for review, sign-off, and subsequent use during capability unit-of-delivery stages of implementation.
Point 6 - A Diagram Is Not a Picture
I’m a firm believer in the value of diagrams that support representing requirements for information system solutions. The common expression associated such diagrams is, “A picture is worth a thousand words.” That expression originated over 100 years ago — well before the introduction of any of our current business analysis diagramming methods.
The form of the pictures that expression refers to is Representational Art. A picture’s content is real-world objects such as a landscape, a person, or an animal. Words could be used to describe a picture’s content, but vision reduces this necessity and thus its worth.
The form of the diagrams that BAs produce is Graphical. Each diagramming method utilizes specific shape, line, and symbol types. The content of those diagrams represents business concepts such as process activities, events, or information. The worth of a given diagram’s content is a combination of:
- The correct use of shapes, lines, and symbols
- The level of domain-specific knowledge of its content providers
- A given stakeholder’s ability to understand both the diagram’s form and content.
Beyond the Visual
Similar to a vision-impaired person not being able to get value from a picture, consider the following diagram example that requires electrical engineering knowledge to both produce and understand:
(Source: visual-paradigm.com/tutorials/how-to-create-circuit-diagram/)
To assist stakeholder understanding of a given diagram-method’s form, a legend should be included that identifies what each shape, line, and symbol type represents.
To assist stakeholder understanding of the terms used to label individual diagram elements, definitions of those terms should be available in a glossary.
To assist understanding diagrams that represent flow, narratives describing each flow should be available.
NOTE: Like documented narrative-form requirements, diagrams should be peer-reviewed for both form and content.
Less is More
Being an advocate of Less is More I recommend avoiding the use of the “full power” of any given diagramming form. I suggest considering three simplification techniques:
- Use fewer shape types, line styles, and symbols in the diagram - shifting their intended meaning to supporting textual descriptions.
- Reduce the number of content elements in a given diagram by providing separate activity-specific views.
- Don’t attempt to track changes visually in a diagram – present only its latest version based on changes tracked within DTR or DDR content.
I highly recommend that diagrams only be used as an aid to stakeholders understanding requirements. DTR and DDR content should be the basis for reviewing, signing off, and subsequent implementing in-scope units of delivery.
Takeaway Point Takeaways
- Diagrams only provide value to stakeholders able to understand their form and content.
- The simpler a diagram is, the more value it is likely to provide visually to stakeholders.
- Additional text can enhance understanding of what a diagram is intended to represent.
- A diagram is not the requirement; it represents the requirement.
Takeaway Action Recommendations
- Keep diagrams as simple as possible.
- Use words to fully describe the “picture”.
Point 7 - Talk Function; Think Data
For me a good day of eliciting requirement details is marked by an SME saying, “That’s a very good question.” My trick of coming up with the majority of those questions is to think about the data involved in the in-scope business activity being discussed. At the same time, I’m aware that the SME’s day job is, or previously was, performing that activity.
My experience documenting requirements for information system capabilities has led me to the following conclusion:
The initial focus of an information system capability is one or more records of a specific record type.
The activity may involve adding a new instance of a record type. Or it may start by referencing a specific instance or filtered set of instances of a record type. In the happy path of a business process that involves referencing a specific instance, that record’s exposed business identifier (e.g. Account Number, Product Code) is available. If not available, an alternate process path is needed that involves other [filter field] values to locate the desired instance.
Notice how the previous paragraph is talking about a business activity’s function, but at the heart of the discussion is data. Documenting the details of an information system capability comes down to identifying the data and action elements the capability involves.
NOTE: Because the capabilities are part of an information system, action elements primarily involve adding, finding, updating, or deleting records.
Functional DTR Discussion Cheat Sheet
Takeaway Point 5 talked about a data dictionary being used to document records and fields managed and reusable within the information system solution. What I like to call a visual index to that detail is a simplified data model diagram of the DD contents. Ideally the diagram will fit on a single printable page. If not, activity-specific subsets can be created.
The following example is from the case study:
A full-sized version can be seen in the example Data Dictionary template.
The visual index is not intended to be shared with stakeholders. It’s meant to be a cheat sheet used by the BA during discussions with SMEs about a specific in-scope business activity. Data elements identified that correspond to existing DD content should require little or no discussion. Data elements identified during a discussion that don’t have corresponding DD entries are the candidates for “good questions”.
The DD template assists by identifying record and field characteristics — some that are common to all elements and others that are record- or field-type-specific. Newly-identified items can be noted on the cheat sheet for subsequent addition to the DD.
To obtain additional understanding of data-related questions for SMEs, I recommend my Data Fundamentals for Business Analysts series. It updates the concepts originally presented in my 1989 book “Fourth Generation Data”. While that book is long out of print, it did serve for several years as the text for data modelling courses run by an international consulting firm.
Takeaway Point Takeaways
- SMEs much prefer discussing functional aspects of an in-scope business activity.
- SMEs have the knowledge about the data involved in an activity but need prompting to discuss it.
- A DD visual index identifies reusable DD content. Once obtained, further discussion is not necessary until all in-scope business-activitiy discussions have taken place.
Takeaway Action Recommendations
- Maintain a solution-specific DD and its visual index.
- Obtain details of new records and fields by asking the SME “good questions”.
- Have all SMEs review the DD content in preparation for signing off the single DDR requirement.
The “+” in My 50+ Year Career
I’m pleased that I’ve been able to continue well beyond retirement age both working and publishing resources intended to help business analysts produce better requirements for information systems.
Hopefully the experiences and recommendations in this article are found to be helpful, and the links to my other published resources provide additional useful information and examples.
Lastly I would like to thank Keri Anderson Healy and Steve Blais — two friend/colleagues, also with 50+ year careers in IT. They have provided valuable feedback during the production of this and other of my published resources.
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].