Skip to main content

Author: Dan Tasker

Requirements In Context Part 4: Keeping High-Level Requirements High-Level

This article discusses the importance of keeping high-level requirements (HLRs) at a high-level. It presents examples of functional, data, report, interface and non-functional requirements. Guidelines are offered for each example about things best left to detail requirements. Lastly, it offers suggestions for managing business user expectations during HLR sessions.

What, Not How

Most often the principle “What, not how” is quoted to remind business analysts to keep requirements at the business level, to not jump ahead to design or solutions. But it’s also useful to keep this in mind when gathering high-level requirements, to avoid getting into detail that is best left for detail requirements.

Related Article: Requirements in Context Part 3: Scope=High-Level Requirements

This series of articles is about contexts for requirements. Every high-level requirement should be thought of as a context for the detail requirements that are to follow. Thus, HLRs should not themselves be too detailed (nor take too long to document). One of the most frustrating things a BA can experience is inviting a business user to a detail requirements session and getting the response, “But I already gave my requirements.” Doing a proper job of starting with ‘what’ should make it clear to all involved that there must be a ‘how’ to follow.

High-level Functional Requirements

The “What, Not How” principle should be applied to HLRs about processes. Consider the following requirement about an on-line purchase process:

The system shall not allow a customer order to proceed to the payment step without shipping details having been identified.

On the assumption that the project scope includes delivering an on-line purchase process, the above requirement is very how-ish. If you visualise a workflow diagram of an on-line purchase process, according to this requirement there should be no path leading to the Provide Payment Details activity that has not gone through a Provide Delivery Details activity.

Workflow diagrams that include decision points, loops and such represent the detail of a given process. The only process diagram appropriate when discussing HLRs should be a quick sketch that represented the ‘sunny day’ scenario through that process. Something like the following:

tasker june19

What a sketch such as this looks like as a high-level functional requirement would be this:

The system shall support customers making on-line purchases including selecting products, specifying shipping details, providing payment details and confirming the order.

A truly high-level functional requirement for a business process should be a simple list of its primary activities. If it’s a complex process with many activities, only a ‘suggestive’ list should be included – just enough so that the reader ‘recognises’ what the process is. This leaves the complete set of activities and flow details for detail requirements definition.

NOTE: If an organisation is interested in exploring business process reengineering (BPR) or business process improvement (BPI), this should be a separate exercise from requirements gathering. While it’s true that simply implementing some automation support to an existing business process should have a beneficial effect, those are small-i improvements. The objective of BPR and BPI is to deliver big-I improvements.

High-Level Data Requirements

The following requirement is one I actually saw in a signed-off HLR document:

Each Customer record must be assigned a unique identifier.

This requirement is about one specific attribute of the business entity Customer. Attribute-specific requirements are detail-level. Consider this alternative:

The system shall support establishing new customers, including capturing details such as name, address, and contact information, ensuring that every customer is uniquely identifiable. E.g. Fred Smith assigned customer number 555123, The Carter Foundation assigned customer number 654287.

This version still mentions attributes, but only as an indication of the detail to follow. The phrase ‘such as’ implies this is not an exhaustive list. The idea is to describe a given entity such as Customer by naming just enough attributes and/or relationships so that the reader recognises the concept. It’s the difference between asking someone to name two of the seven dwarves from Snow White and asking them to name all of them. Your subject matter expert (SME) should be able to come up with indicative attributes in seconds. An example or two is another way to ensure that the concept is clear.

From the simple examples included in the HLR above we understand that customers can either be individuals or organisations.

High-Level Report Requirements

Up until now we have distinguished high level from detail level keeping in mind the “What, not how” principle. For reports, we still want to avoid the ‘how’, but the ‘what’ should be augmented by adding four additional Ws – Who, When, Where and Why. Journalism students used to be taught that the first paragraph of a news story should always include information about each of the five Ws.

An example of a high-level report requirement in user story format that includes all five of the Ws is:

As a Customer [who] I want to receive an Order Confirmation that includes details such as the items purchased, amount charged and expected delivery date [what] sent to my email address [where] following the completion of each order [when] so that I have an off-line record of my purchase [why].

The ‘Shall’ version need not be very different – beginning with “The system shall provide a Customer with …”

Some memory joggers as to what reports may be needed are:

  • Event Based – milestones within a process or at its end, or alerts triggered by thresholds being reached
  • Periodic – daily, weekly, monthly or annual reports
  • Statutory – required by government or other regulatory bodies
  • Management – used to monitor progress against plans or budgets

As with the functional and data HLRs, the objective is to set the context for detail to follow. There is really no difference between the need to deliver a function and the need to deliver a report (that is truly needed). There should be one HLR for each, kept to a high-level description that establishes an understanding of what it is.

High-Level Interface Requirements

The previous article talked about context diagrams that represented a project’s scope. The things outside the system boundary in such diagrams represented either types of business users or else other systems. Each system represented at the context diagram level will need at least one interface HLR. These should cover the same five Ws described above for reports. An example of this in ‘shall’ style is:

The system shall support sourcing of foreign exchange rates [what] from the European Central Bank [where] on a daily basis [when] to support currency conversion when the on-line customer [who] deals in a different currency than the supplier of a product [why].

High-level Non-Functional Requirements

There is no question that business information systems must be secure, that they should be usable, and they should perform well. Continuing with the ‘what, not how’ principle, I believe it appropriate to include just a single HLR that lists exactly which NFR types will need to be detailed at some point in the project. This single requirement might be worded something like:

The system shall satisfy details of the following types of non-functional requirements:

  • Security
  • Usability
  • Performance
  • Availability

Exactly when the details of NFRs should be addressed will depend on what the next step of the project is. In the meantime, there is at least one HLR included acting as a context for details to follow.

Gathering ONLY High-level Requirements

The problem with inviting business users to a high-level requirements session is that many believe that this is where they are expected to discuss their requirements. In addition, some bring with them their pain points from the business information system. The ‘unique identifier’ requirement mentioned above was most likely contributed by a user that was having trouble identifying customers.

I would suggest that a better name for an HLR gathering session would be “Requirements Planning.” The invitation should include the agreed project scope items. These set the context for identifying HLRs. The objectives of the session should be stated to be something like:

• To list specific business processes or activities, types of data, reports, and interfaces that are expected to be delivered by the project.

• To identify SMEs for each of these items to participate in subsequent detail requirements sessions.

The previous article in this series demonstrated how ‘starter’ HLRs can be derived from function-based scope items. Having these drafted in advance of an HLR session they can be presented as examples for the appropriate level of detail that is being sought.

Next Time – Where To From HLRs – Build or Buy Context

Where this article highlighted the importance of keeping HLRs high-level, the next article focuses on the importance of detail in detail requirements. We also discuss the rationale for this detail for different delivery contexts (i.e. build or buy).

Requirements In Context Part 3: Scope = High-Level Requirements

The first article in this series established the context of requirements being addressed are those that relate to business information systems and that various contexts have an impact on those requirements. The second article addressed the first of these contexts – Functional. That context was further divided into three conceptual levels labelled Functions, Processes and Activities. An example high-level requirement was presented at each of these levels.

Project Scope

This article moves on to a different context – Project Scope. We will see how scope statements, when making reference to business functionality, leads directly to high-level requirements.

Gathering requirements for a business information system is most often done within the context of a project. Approval of a project includes its sponsors signing off on its scope. The scope of a business information system project is typically defined in functional terms. Items in scope make reference to (or should make reference to) business functions, processes and/or activities that are to be delivered.

Related Article: Using Feature Trees to Depict Scope

A Context Diagram Is Worth A Thousand Words

In addition to the bulleted item list of scope, it is very common for the project initiation document to include a context diagram. The objective of a context diagram is to illustrate what is inside the system and what is outside. Things outside the system represent sources and/or consumers of data. The original form of context diagram comes from Dataflow Diagramming (DFD). The top-most level of functional decomposition using DFDs was considered a context diagram. The Unified Modelling Language (UML) Use Case modelling also supports a form of context diagram. Both of these diagramming techniques represent ‘the system’ and both portray things outside the system boundary. The DFD term for these outside things is External Entity. The UML term is Actor. The definition of these two terms is virtually identical.

tasker part3

A DFD context diagram says nothing about the functions inside the system. That is left to subsequent levels of functional decomposition. Clues are provided by labels given to the data flows. The Use Case context diagram provides more of a clue to the functions within scope by including named use cases. Data flows in a DFD context diagram connect only to the system. Actor connectors in a Use Case context diagram connect to one or more specific use cases within the system.

High-Level Requirements From Project Scope

Examples of high-level requirements were presented in the previous article based on a high-level business function, a medium-level business process and a low-level business activity. We are about to present an example of a project and its scope. As mentioned above, the scope of business information system projects is very often expressed in functional terms. It should, therefore, be possible to derive high-level requirements from scope items.

Consider the following situation involving a large hypothetical on-line retailer we will call Nile.com:

Nile.com has a well-established purchase process for its on-line customers. The check-out portion of this process includes activities for identifying the intended shipping address and for providing some form of payment. What the process does not currently include is anything to do with tax on items being purchased. As the result of pressure from various tax authorities this needs to change.

In establishing a project to deal with this change in the business environment the following scope items were agreed by the business sponsor and signed off:

  • Maintaining tax-related details for designated tax authorities
  • Determining applicable tax on items being purchased
  • Including applicable tax with purchases
  • Accounting for tax charged

The Use Case form of context diagram for this example would look like this:

taster part3 2

Scope items will seldom be stated so conveniently that they can be converted one-for-one into the names of use cases. For the sake of brevity, please accept that the scope items in this example are “ones that I prepared earlier.”

The objective of this article is to show that it is possible to derive high-level requirements based on a project’s scope. The following are examples of such requirements from the scope in this scenario:

Scope Item 1 – Maintaining tax-related details for designated tax authorities

The system shall support an administrator maintaining tax-related details required to perform tax determination. This includes establishing tax authorities that are the source of tax rates and to whom collected taxes need to be paid. It also includes mapping of products to tax rates for each authority where there are product-specific rates or specific product types that are tax exempt.

Because charging tax is new to this organisation there may not be an in-house subject matter expert available when it comes time to sorting out the details for this requirement. Until more is known this high-level requirement acts as an appropriate placeholder for what is likely to be a number of business processes. One would likely be needed for setting up new tax authorities, one for setting up the tax rates and where applicable, one for specifying different rates for different product types. The requirement from a business perspective is fairly straight forward – maintain whatever details are necessary to be able to charge tax. The devil is in the detail.

Scope Item 2 – Determining applicable tax on items being purchased

The system shall be able to identify the appropriate tax that applies to the purchase of a given product based on the product type and the tax authority(s) that have jurisdiction where the shipment is to be delivered.

Where the previous requirement calls for wholly new business processes to be supported within the business information system, the functional context of this requirement would be somewhere within the “Identify the shipping address” activity within the “Purchase” process. At this point the product(s) are known, and the shipping address details can be used to determine any applicable tax authority(s). Subsequent detail requirements would get into how an appropriate tax rate is determined and specifics of where that rate is used in calculating the total charge to the customer.

Scope Item 3 – Including applicable tax with purchases

The system shall present to the customer all applicable tax amounts as part of the purchase process.

This statement should be sufficient as a high-level requirement from a business perspective. Part of the detailed requirements analysis would include identifying all of the places where the customer ‘sees’ purchase price details. Each of those places will require modification to include whatever tax applies, if any.

Scope Item 4 – Accounting for tax charged

The system shall report charged tax amounts as a distinct component of each purchase to the general ledger system identifying appropriate GL Codes and the designated tax authority.

Wherever money is involved the organisation’s general ledger needs to be kept informed. In this case it is unlikely that there will be any new processes or even activities required. Reporting to the GL will be in place for the current untaxed purchases. This reporting will just require an enhancement to include the tax amount and its corresponding GL Coding. There should also be an existing Accounts Payable process that handles making payments to suppliers for the organisation. The different tax authorities that are to receive payment of collected taxes should be covered under that process.

Next Time – Keeping High-Level Requirements High-Level

The four requirements derived from the project scope items would not be the only ones for the whole project. But it must be said that they cover the agreed scope of the project and that they are high-level (not slipping into detail). Next time we will look into how to keep high-level requirements high-level when dealing with stakeholders that are asked to participate in the context of “Gathering high-level requirements.”

Requirements In Context Part 2: The Functional View From 10,000 Feet

In the first installment of this series it was stated that the overall objective of these articles is to improve the quality of requirements produced by business analysts. Following the adage that “Context is Everything” it established that a number of different contexts will be explored. And in keeping with this principle it set business information systems as the context of the requirements to be addressed.

Classic Business Functions

My very first position as a business analyst 30 years ago was with a company that had just completed an enterprise-wide planning effort.(1) They had gone so far as to remodel one of their conference rooms for the specific purpose of displaying the results on multi-layered whiteboards. The most prominent board displayed a functional model of the business. It was said to be a view of the company from 10,000 feet up. The functions were organised into three categories: Management, Support and Line of Business.The following diagram is a slightly simplified version of that model:

taser 5 17

In my first article I presented the classic “Swings” cartoon. It is a classic because it has remained relevant all these years. I consider the high-level functional model presented above to be a classic. It too has stood the test of time. Throughout my years as a business analyst, working in a wide variety of industry segments and government agencies in three countries, this model has proved to be both relevant and useful.

Related Article: Just Know It!  Requirements in Context

Not all organisations utilise every one of the functions shown. And some organisations have multiple lines of business. For example Walt Disney – Film production would be one, theme parks another. In this style of model, each would have its own ‘Line of Business’ functions to provide contexts for dealing with very different products. Regardless of the numbers of lines of business, the Management and Support functions are applicable across the organisation.

Enterprise Resource Planning

Thirty years ago using a model like this to plan an organisation’s business information systems was leading edge. Database management systems had been around just a few years. Their use typically involved one-for-one replacement of application-specific files. A batch processing inventory management system would be upgraded to an online inventory management system supported by an inventory database. A batch processing sales management system would be upgraded to an online sales management system supported by a sales database. And on and on.

High-level functional models like this were used to demonstrate to the organization that a shared set of data could and should be used to support multiple functions across the business. The idea was to stop developing application-specific information systems and start developing an enterprise-wide one. Fast forward to today and this vision has become business as usual for many organisations. It is common today for an organisation to have a relational database that holds data utilised by multiple business functions. Some of these systems have been developed in-house. Others utilise one of the commercially available Enterprise Resource Planning (ERP) systems. Probably the original and best known of these is SAP.

The following is a list of integrated SAP modules that an organisation to pick and choose from:

  • Human Resource Management
  • Production Planning
  • Material Management
  • Financial Supply Chain Management
  • Sales and Distribution
  • Project System
  • Financial Accounting and Controlling
  • Plant Maintenance
  • Quality Management

Quite a striking correlation between these modules and the high-level functions from that 30-year old model.

High-level Requirements From High-level Functions?

This series of articles is about requirements in context. The Functional context is where we are starting. The functions from the 10,000-foot level are the most general functional context I can imagine. Could these be used to draft requirements? I can think of one scenario where they could – an organization interested in acquiring an ERP system. Here is an example of one such high-level requirement:

“The system shall support Accounting processes integrated between themselves and with processes of other functions.”

Each ERP function the organisation is interested in should have its own requirement naming a high-level function it wants within its integrated system. Each would be assigned its own priority. Some would likely be must haves while others might only be nice to haves. (Who am I kidding? – we all know that to business users every requirement is a ‘must have.’)

Processes within Functions

The view from 10,000 feet is an interesting functional context, but outside of acquiring an ERP system we need business functions closer to earth. Fortunately the majority of functional modelling techniques include the concept of functional decomposition. That technique used to produce the model above offered a simple three-level decomposition scheme. The things at the top level were called Functions. A level below functions were things called Processes. The third and lowest level things were called Activities.

Functions were considered to be ‘ongoing’ activities. A person working in Accounting or HR does their job year round, year in and year out. Processes in the context of this model were defined to be things that have a start and an end point. A given Function typically would decompose into 10-ish Processes. Again using SAP as an example, we see its HR module breaks down into 12 processes:

  • Organizational Management
  • Personnel Administration
  • Recruitment
  • Payroll
  • Travel Management
  • Personnel Management
  • Time Management
  • Compensation Management
  • Training and Event management
  • Wages
  • Personnel Development
  • Workforce Administration

It’s easy to envision most, if not all of the above processes having start and end points. For example, while it could be argued that Recruitment goes on continuously, in reality filling a specific position starts with some form of notification of the opening and ends ideally with a successful candidate coming on board. Here is an example of a high-level requirement utilising a Process context:

The system shall support the recruitment process including keeping records of published notifications, candidates, interviews and proof of fairness during the selection process.

Activities within Processes

The term Activity can be defined as the individual steps in a process. Visualise a workflow diagram. The boxes in the diagram that don’t themselves require further decomposition would be considered activities. The basic idea is that an Activity is that it should be simple enough that an individual is able to complete it in a single ‘sitting.’ No need to hand the work off to anyone else mid-activity or to have to wait for some other activity to complete. An example of an activity within the Recruitment process would be one called “Make Offer to Candidate.” An example of a high-level requirement ustilising an Activity as a context would be:

The system shall support keeping a record of offers made to selected candidates.

I have used a variety of functional modelling techniques from dataflow diagrams to business process modelling notation (BPMN). Regardless of the terminology used in any particular method, I have found the definitions of the three functional levels presented above to be excellent guideposts for both functional modelling and drafting requirements.

Next Time – Project Scope as a Context for High-Level Requirements

Gathering of requirements is typically managed within a project, and part of managing a project is establishing its scope. Requirements are expected to address the things within this scope. Next time we will look at scope and how high-level requirements can be derived directly from it, and actually as part of the scoping effort.

(1) The enterprise-wide planning methodology utilized by the company described was called Strategic System Planning (SSP) developed by Robert Holland.

Requirements In Context Part 1: Just Know It!

I have long been a believer in the saying “Context is everything.” As a business analyst dealing with business users, understanding the context of the topic of discussion is essential.

In thinking about what constitutes quality requirements, it occurred to me that there are a number of additional contexts that play a role. Examples include the organizational maturity level (from Informal through to Optimized) and delivery context (green fields through to package acquisition).

Related Article: Want Faster Requirements? Build Them Like a Snowman!

This is the first in a series of articles about business requirements. My primary objective is to help business analysts improve their elicitation and documentation of requirements. With an increased awareness of multiple contexts I believe that the quality of the requirements documented can be improved, and subsequently, lead to the better design, development and implementation of business systems.

Mark Twain is credited with saying, “Everyone talks about the weather, but nobody does anything about it.” The equivalent saying in the IT context would be, “Everyone agrees that good requirements are essential, but nobody does anything about them.” A perfect illustration of this is the classic IT cartoon “The Swings”:

tasker article

What is not funny about this cartoon is that the situation it depicts is as true about business systems delivered today as it was when the above version was published. Over 40 years of struggling, and most often failing to meet user expectations, in spite of unimaginable improvements in technology.

I have no illusions that what I intend to present will magically make it all better. But these articles are at least my attempt to do something about it. If you are reading this, it means you are interested in improving your BA skills. Hopefully learning about the impact of different contexts on requirements will lead to that.

The Business Information System Context

I find it virtually impossible to take off my business analyst hat. Any time a family member or friend mentions that they want something – a new car, an electrical appliance, I immediately go into ‘requirements mode.’ I start asking questions intended to help them focus on their thinking in order to lead to making the best choice.

It occurred to me that it as I begin to present the various contexts related to requirements that I should set the context for this series of articles. The context of requirements that I intend to focus on is business information systems. And while a complete information system includes a hardware and a network aspect, the requirement contexts that will be discussed will not include these technical aspects. The requirements contexts will focus on business analysts interacting with business users to deliver the functional and information components of a system.

Please note that when I use the term ‘system,’ from a requirements perspective that doesn’t mean that every requirement will result in a computer-based solution. Having gathered requirements, a subsequent exercise is to determine which of them will be given automated support and which will be left as manual processes.

Functional and Information Components

The earliest “computers” were primarily electronic calculators. They allowed complex formulas to be broken down into individual computational steps. Having expressed these steps in a language the computer could understand the resulting instruction set was ready to receive the data to be manipulated. The end product was a set of calculated results.

When businesses began using computers, their objective was to maintain data about their business. Computational requirements were minimal. Simple things like adding or subtracting deposits and withdrawal amounts from a customer’s account balance. The original computerized business systems all performed their functions by reading in batches of data, operating on each record as it went through the system, and producing individual results before the next record was processed.

With the advent of database management systems and access in ‘real time’ to computer applications, more and more business processes could be supported by computers. Today virtually every office worker has a computer on their desk. And thanks to wireless networks and portable devices workers (and customers) outside of the office have access to the information they need when they need it.

With the focus of business information systems being the support of functions that capture and utilise data I offer a variation on the Nike slogan “Just Do It”. The objective of the business information systems we gather and document requirements for should be “Just Know It.”

Functional Context / High-level Requirements

Having established the context for these articles to be business information systems, the journey itself will begin in the next article. In it, I will present a technique I have used for many years to help establish the functional context for a requirements gathering effort. The more common term for this functional context is “Project Scope.”

I will also discuss the possibility of combining the scoping exercise with the producing of high-level requirements. The result of doing this reduces that requirements task down to hours rather than days (or weeks). This will be the first of several demonstrations of the strength of applying the thinking that “Context is everything.”

The Magic Behind Functional Requirements – Data!

For me a good day of gathering requirements is marked by a business user saying, “That’s a very good question.” In the majority of instances the trick of coming up with those questions is the same – while talking to users about their business processes, I am mentally mapping the information those processes involve to a data model.

In a previous life I was a Data Administrator. Relational database technology was new and ‘normalisation’ was a magical art. Apprentice data analysts could get to third normal form. Full data wizards understood fourth and fifth normal form. Hard to believe it now but we ran sessions with business users that focused purely on data. We asked them to put their processes out of mind and focus only on their information requirements. Our deliverables were entity/relationship models intended to support the development of enterprise-wide, reusable databases. It was a VERY painful process for all involved.

I’d estimate that data administrators (myself included) spent about 30% of their time documenting business data requirements and the other 70% debating with other data administrators about such things as naming standards, domains, and whether “Double-headed arrows,” “Crows Feet” or “A Big Dot” was the best way to represent the “Many” end of relationships on Entity/Relationship (E/R) diagrams. I really miss those days – NOT!

Fast forward twenty-something years to today. The Unified Modelling Language has morphed E/R diagrams into Class Diagrams (although Relational databases for the most part are still the norm rather than genuine Object-oriented databases). When people talk about requirements the two main types are Functional and Non-Functional. Data requirements are typically relegated to entries in a glossary or one or more E/R diagrams in an appendix.

Business users now, as then, have zero (or less) interest in looking at a data model. However, they are more than happy to be shown a screen ‘wireframe’ representing the way a system would present data to them in support of their business process. The trick, at least in my case, is applying my data perspective during discussions of these wireframes, but without using the “E” or “R” words. Most typically a screen equates to an entity (e.g. Customer, Contract, Order). So does a displayed table of items (e.g. Order Line Item, Payments). Fields in the screen (or columns in the table) either are ‘facts’ about that entity or reference some other entity (e.g. the Customer ‘named’ in an order or the Product ‘short description’ in an order line item).

OK, back to the magical source of ‘good’ questions. The basic data normalisation technique is ensuring that each attribute is a fact about the most appropriate entity. [“The key, the whole key and nothing but the key, so help me Codd.”] If not, then it is a fact about some other entity.

For example in an Order Line Item, “Quantity” is definitely a fact about the Line Item. The “Product” being ordered is a fact about that Line Item, but because there are a bunch of ‘facts’ about Products irrespective of them being ordered, there needs to be a Product entity. Users entering Line Items need a way to ‘identify the product’, and having done so the screen is populated by fields that are facts taken from the identified instance (e.g. short description, unit price). A “good question” might be, “When a Product is ordered, is the Unit Price the same in all cases, or can the unit price be different (e.g. Customer-specific price schedules)?”

Another ‘good question’ that has its basis in normalisation is, “Can that fact have multiple values at the same time (e.g. an Employee being classified as having multiple Skills)? Or the cardinality of a relationship (e.g. can a Contract involve more than one Supplier?).

If you have data analysis skills, I encourage you to apply them during requirements gathering. If you are light on data modelling skills, I encourage you to learn more about the subject. Regardless, I encourage you to keep these skills hidden from your business users and let them think you have magical abilities to ask ‘good’ questions.

Anyone else, “been there, suffered that”? If so please add any examples and/or tips for gathering requirements without diverting Business Users from their focus on their processes.

Don’t forget to leave your comments below.