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:

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).