Skip to main content

Author: Dan Tasker

The Problem With Business Requirements: Series Wrap Up

Written by Dan Tasker on . Posted in Articles. 1 Comment on The Problem With Business Requirements: Series Wrap Up

There are high-level requirements, there are detail requirements, and then there is this in-between thing called business requirements.

The problem with business requirements is that they are allowed to be high-level, detailed or anything in between. As long as some business user says that they require it, the business analyst is duty bound to record it. The world (and business information system projects) would, in my opinion, be a much better place if there were no business requirements.

What I have found in my years of mentoring is that many BAs have trouble with the distinction between high-level and detail requirements. A primary objective of the Requirements In Context series that I just completed was intended to help make this distinction. This article is intended to be a summary of takeaway points from the series. Two of those points are:

  • High-level requirements should always have a business (and project) context
  • Detail requirements are most easily discovered when focusing on an HLR context.

Part 1 of the series introduced the need for improved requirements, presenting the classic ‘Swings’ cartoon as evidence that things do not appear to have improved much over the years when it comes to delivering business information systems. Part 2 talked about business functions as a context for high-level requirements. A generic functional view from 10,000 feet of an organization was presented as the ultimate business context. This generic business model was comprised of management functions, support functions, and line of business functions. High-level business functions were seen to act as a context for a number of business processes within that function. Each process, in turn, was seen to act a context for a set of business activities.

High-Level Requirements Guidelines

Part 3 of the series talked about project scope, and how scope statements and context diagrams can be excellent sources of HLRs. Examples were given of turning scope statements directly into high-level requirements. Part 4 provided guidelines for keeping high-level requirements high. It recommended that business analysts and project managers think of this exercise as ‘requirements planning’ rather than ‘gathering high-level requirements.’ What you definitely do NOT want to happen is for an HLR gathering session to degenerate into a business requirements gathering session.

Before diving into the subject of detail requirements, Part 5 of the series discussed four ‘build or buy’ delivery contexts (i.e. takeaway points):

  • Build – In-house with embedded SME (e.g. full Agile)
  • Build – In-house without embedded SME (e.g. Agile-like, Waterfall)
  • Buy – a custom-built solution (outsourced development)
  • Buy – a package solution (with optional customization)

It turns out that only the first of the above contexts allows for getting by without well-documented detail requirements. This is possible because with full Agile, the Scrum Team includes a business subject matter expert that is available full-time(ish). Performing the role of Product Owner, this person provides the necessary details just in time for each sprint.

Detail Requirement Form – User Story or Shall Statements?

I did my best in the series to stay out of the debate over the best form of requirement statements – User Stories or Shall Statements. At the end of the day, I believe that content is what’s most important, not form. Meanwhile, I will say that I like user stories. The main reason is that they have a clearly defined structure – a single sentence containing the elements who, what and why. Conversely, Shall statements just get the ball rolling with “The System shall …”. After that, it’s pretty much a free-for-all. A requirement in Shall statement form can be a single sentence, or it can run on for multiple pages. And don’t get me started on ‘shall’. I’ve actually never met a business analyst who likes the term in that context. The only thing worse (in my opinion) is replacing it with a term that implies the priority of the requirement. e.g. “The System must …”.

Detail Requirement Content – Seven Plus Or Minus Two

A detail requirement can be about a single attribute such as the ability to change the status of an order. Or it can be about a long list of attributes that are intended to be included in a screen or report. When there are a small number of fields involved (a rule I’ve always been partial to is “seven plus or minus two”), the content of the requirement can be contained within the user story or shall statement. The following example is taken from Part 5:

As the system I want to receive daily currency exchange rate data from the European Central Bank so that I can convert purchase amounts from a supplier currency to a customer’s preferred currency.
Acceptance Criteria
  • Given access to base exchange rates made available from European Central Bank
  • When the ECB exchange service makes new rates available
  • Then the following details about each currency is recorded and available for use converting between currency pairs:
    • To Currency e.g. USD
    • Effective Date
    • Exchange Rate From Euro e.g. 0.89
    • Rate Type e.g. Mid-Market

Note that in the above example the attributes involved ended up in the acceptance criteria. I consider this part of the requirement. If anyone has a good example of a user story that handles detail in the user story ‘sentence’ itself, please do share or describe it in an added comment below.
Conversely, I strongly recommend not trying to name long lists of attributes in a detail requirement. Instead, it should be possible to manage that amount of detail using a context-specific template. The following contexts are suggested as template candidates:

Each of the above context types includes a link to the series article discussing it along with an example detail requirement for the context. Here is one such example from Part 7. Again we see the acceptance criteria as a place to include a reference to where the appropriate full/complete requirement detail has been recorded:

The system shall display the details of the order that a customer placed on-line in response to the order having been submitted.
Acceptance Criteria – Order Completed Successfully
  • Given a customer placing an order on-line
  • When the customer has completed the order process including confirming the order
  • Then the details of that order are displayed as per the “Customer Order Confirmation Screen” specification found Appendix C.

The final context in the series is derived data. It’s discussed in Part 8. As with the context types listed above, simple derivations may be included within the requirement itself while more complex derivations might benefit from being described in supporting documentation referenced in the requirement statement.

Why So Much Detail?

As mentioned at the beginning, business requirements that contain only ‘middle of the road’ detail serve little purpose. Designers, developers, and testers don’t have sufficient information to do their jobs in three of the four delivery contexts listed. When additional detail is needed (and it certainly will be) either a business SME will need to be contacted, or else the project ends up being yet another casualty of ‘The Swings.’

Making use of context-specific templates can help guide BAs to record sufficient detail to deliver each of those items ‘in context’ for the project, based on HLRs that identify them. And with this level of detail business information systems can be built that (hopefully) satisfy the business needs.
So, as promised – takeaway points from the Requirements In Context series:

  • High-level requirements can be sourced (partially) from project scope and context diagrams
  • Keep high-level requirements high level
  • Detail Requirements are most easily found within an HLR context
  • Detail requirements should be fully detailed (not just listed), using context-specific templates when needed

And a bonus takeaway point introduced in this summary article:

  • Avoid producing Business Requirements

Requirements in Context Part 8: Derived Data

Written by Dan Tasker on . Posted in Articles.

It’s the job of Business Information Systems to know stuff. They are able to know stuff either because they have been told the stuff or because they have been told how to derive stuff from the stuff they know.

This article is about deriving stuff within the context of detail functional requirements.

Contexts For Derived Data

In parts 5 and 7 of this series we saw three detail requirements contexts that can involve derived data:

  • Interfaces
  • Reports
  • On-Line User Interfaces

There is a fourth context not yet discussed – Internal Processes.

Content Detail for Internal Process Requirements

An internal process is a cross between a report and an input interface. It’s like a report in that it runs at a scheduled time and has selection criteria that finds all of the records it needs to work with. Having been initiated and with the selected records the internal process behaves like an input interface, working its way through those records with the result being new records inserted into the database and/or existing database records updated.

An example of an internal process for a Banking Information System might be “Credit Customer Accounts With Earned Interest.” Scheduled to execute daily, the process would:

  • Find all of the Customer accounts that are due to be paid interest.
  • For each account found
    • Look up the rate of interest that applies to the account type
    • Calculate the amount of interest earned
    • Create a credit transaction for the customer containing this amount
    • Post the transaction (resulting in the account balance being updated with the interest amount)

A detail requirement for the “Earned Interest” internal process would follow the same pattern as for reports and interfaces described in Part 5 – a single detail requirement that names the process and references its details recorded in an Internal Process Spec. The drafting of this requirement either as a User Story or Shall Statement is left as an exercise for the reader (pick your preferred format). Extra credit will be given for including acceptance criteria.

As indicated in the previous articles, the detail requirement does not mention each field involved. Rather the detail, including identifying individual fields involved, is relegated to a template-based specification appropriate each of the context types. In cases where a field represents derived data, a description of the derivation should be included as a comment associated with the field. We will see examples of these below.

Data Derivation Descriptions

I like to think of derived data, and their corresponding descriptions as being one of the following three types:

  • Grown Locally
  • Phone a Friend
  • Build an Ark

Grown Locally – With this type of derivation, the values needed for the derivation can be found amongst the other fields in the spec for the given context. So when you are describing the derivation, you are referencing fields that are listed right there in the spec.

Example 1 – Producing an Invoice, the query has returned all of the line items being included in the report. Each Line Item includes the “Total Amount” for that line. So when it comes time to derive the overall “Invoice Total” field value the necessary items to sum up are all available. If the invoice can involve additional fees or charges, then the derivation would involve them as well.

Given fields called “Line Item Total” and “Shipping Charge” listed in the report spec, the derivation description in the comments field for “Invoice Total” might be:

Sum of Line Item Total values plus Shipping Charge

This description is a verbal version of a mathematical formula. The equivalent mathematical version would look something like this:

Invoice Total = Sum(Line Item Total) + Shipping Charge

In cases where a derivation formula involves lots of fields and/or more complex calculations it can be clearer to use abbreviations:

LIT = Line Item Total, SC = Shipping Charge
Invoice Total = Sum(LIT) + SC

NOTE: I’ve kept the example that uses abbreviations the same as the previous two forms. It would probably not be necessary to resort to this style until the number of fields or the complexity of the formula gets larger. When you encounter these, you’ll recognize the benefit of using both the mathematical form and abbreviations.

Example 2 – Presenting Customer Name on a report or screen as a single field derived by stringing together the locally available non-derived fields Title, First Name and Last Name. The derivation description in the comments field might be one or the other of the following:

Customer Name is a concatenation of Title, First Name and Last Name. E.g. Mr. Fred Smith
Customer Name = Title + [space] + First Name + [space] + Last Name E.g. Mr. Fred Smith

Derivation descriptions should include examples wherever possible. Examples help confirm what the business is wanting and provide guidance for development and testing. Note that both description versions in Example 2 expect there to be spaces between the concatenated fields. The first description didn’t mention anything about spaces, but the included example showed that spaces were part of the derived result. The second description indicated spaces explicitly. Even so, an example is worth including.

Both Example 1 and 2 above involve simple formulas describing how to derive a field from existing data using arithmetic operators or via string manipulation. Derivations can also involve logical operators such as greater than, equal to and less than either as simple pairs or combined with And, Or and Not. The following variation on Example 2 involves a single condition. The additional fields are assumed to be ‘grown locally’ as well:

Example 3 – Presenting either a Person Name or an Organisation Name depending on Customer Type:

If Customer Type is equal to “Person” then Customer Name is a concatenation of Title, First Name and Last Name
Otherwise, Customer Name is Organisation Name. E.g. ‘Starbucks’, ‘Mr. Fred Smith’

Phone a Friend – This type of derivation involves one or more values that are not amongst the fields in the context. They need to be sourced from the information system’s database.

Example – Grocery item purchases being captured using an on-line POS terminal. Scanning the barcode of each item identifies the product but the “Current Unit Price” needs to be looked up. The derivation description in the comment for this field might be:

Use the product’s BarCode and the current date/time to find the Product’s Current Unit Price

Note that his description is very ‘what, not how.’ No mention is made of what table contains the field that will have the value needed. Those details should be left to the solution designers. The derivation description is best left to what the business knows at the time the derived value is needed. If it turns out that additional details are required to find a result, then the SME should provide the correct information for the BA to include in the description.

Data derivations can be a mixture of Grown Locally and Phone a Friend. If a derivation formula involves one or more fields that require lookup, then the description might best be split into multiple steps. The Phone a Friend steps should be described first so that the values become available. They can then be used as if they were ‘local’ in the remainder of the derivation.

Build an Ark – When derivations go much beyond a simple formula, a small number of database lookups and/or conditions the form of the derivation is called an algorithm. The comment field of a detail requirement spec is not an appropriate place to describe an algorithm. It really needs its own separate specification [template] and its own [single] requirement.

Content Detail For Algorithm Requirements

Algorithms will typically have a business activity name such as “Determine Price” or “Determine Eligibility”. This activity would very likely appear as its own ‘box’ in at least one business workflow. Descriptions of algorithms fall into the category of ‘A picture is worth a thousand words.’ In this case, that means providing something like a UML Activity diagram. Those types of diagrams are designed to show sequences of steps and branches based on decision points (i.e. conditions). The pre-UML name for an Activity diagram is “Flow Chart.” The diagram (and supporting text and definition of fields used) represents the details of the functional requirement.

Like the contexts discussed previously, a single requirement should be used to represent the detail. An example based on our ‘pricing’ activity would be as follows:

User Story Format:

As a Customer, I want my contracted rates used when pricing purchases because those rates are legally binding during the term of my contract.

Shall Statement Format:

The system shall use the currently contracted rates for a customer when calculating the price for purchases made by that customer.

Both requirements should include acceptance criteria:

Acceptance Criteria

  • Given the current contracted rates for a customer
  • When the customer purchases a product
  • Then the price charged for that product is the result of those rates being applied to the “Customer Pricing” algorithm described in Appendix C.

The activity diagram and accompanying description are produced by the BA in conjunction with the SME that understands the algorithm. Some of the fields involved will be ‘locally grown’ and some will involve ‘phone a friend’.

Requirements In Context – Just Know It

This series has been about business information systems and how it is their responsibility to know what users need to know to support their business processes and activities. What the system ultimately knows is field-level detail. This detail is sourced from input interfaces, on-line interfaces, internal processes, and algorithms. Providing that detail to users and other systems is through reports, output interfaces, and on-line user interfaces. Detail requirements, at the end of the day, is about field level details in context.

The next and final article will summarise the key ‘take-away’ points from the series. Following that, there will be a quiz.

Requirements in Context Part 7: Detail Online Functional Requirements

Written by Dan Tasker on . Posted in Articles.

The standard for business information systems today is on-line access by business users via graphical user interface (GUI) screens.

In addition, the current trend is towards customer self-service via web-based portals. This article deals with detail functional requirements for these on-line interfaces.

Related Article: Requirements in Context Part 6: The Evolution of Computerized Business Functions

Screens are similar to reports in that there are aspects of both form and content to the data being displayed. Form is about usability and understandability. Content is about the fields necessary to the business function(s) that the screen is intended to support. Detail functional requirements should definitely address screen content. The issue of form need only be addressed in situations where there are specific business requirements that must be met, such as where a screen is intended to capture data from a paper-based form that has a pre-defined layout.

NOTE: The concept of usability testing, which more typically applies to customer-facing screens, is outside the scope of this series.

Screens significantly differ from reports when the screen is intended to be used for data capture as well as display (a trick reports have yet to master). Additional information needs to be recorded about each input field as part of detail functional requirements. This detail will be addressed below. But first, we need a context for these fields. That context is the screen that contains the fields. So the initial question during detail requirements is, “What screens are required?”

Screens Supporting Business Activities

The reason a business user requires a screen within a business information system is that they are performing a particular activity. The reason a customer requires a screen is that they are at a particular point in a product life cycle (e.g. applying for, purchasing, transacting, status checking).

A separate but related activity to detail requirements gathering is business process modeling. Part 2 of this series talked about business models in general and the concept of functional decomposition. Part 4 of the series talked about defining high-level requirements that made reference to a specific business process or activity. Being referenced in a high-level requirement (HLR) indicated that the process or activity was in scope and due to be considered in more detail from a requirements perspective.

Ideally, the more detailed process models would either be done prior to or else at the start of detail requirements gathering. The modeling of in-scope processes should be done to a level where activities represent a single user performing a single task without the need for interruption or involvement by other users. Those activities that are intended to include some on-line involvement then become the focus of detail requirements.

The example functional HLR from Part 4 was based on the following high-level process diagram:

tasker june19

The HLR read:

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

The fully detailed process model would account for a number of product selection-related scenarios including de-selecting items or changing quantities. The business may want customers to have the ability to save and choose from multiple delivery addresses. They would also specify what payment methods they want to be supported. Then there is always the exception scenario to be modeled where the order is abandoned rather than confirmed.

What we are primarily interested in is the fields required to support a unit of work. Whether those fields are all bunched into a single screen or spread out across multiple screens is a combination of usability and convenience. A rule of thumb is that users who perform a task often prefer one big screen that allows them to focus on getting the data entered whereas casual users appreciate the fields split out across multiple screens, grouped in easy-to-understand bunches and lots of help text.

The point from a detail requirements perspective is that there is some screen context that allows the fields to be talked about and specified in support of the activity.

Field-level Detail Requirements

Part 5 of this series discussed the necessity for detail requirements to cover every field that is needed by the business. The same template concept that was presented in that article for reports can be applied to screens. This allows the field-level detail to be captured in the template rather than in individual field-specific requirements.

A template for fields included on a screen should begin by capturing details about the screen itself. Those details should include:

  • Name (e.g. Order Confirmation)
  • Description of access path(s) to it (e.g. via what menu options or prior workflow step(s))
  • Description of navigation path(s) from it (e.g. if part of a workflow)
  • Description of any security considerations (e.g. user roles that have full or partial access)

The template should then provide for details about individual fields including:

  • Label or column heading
  • Display only or editable
  • Conditions under which a value is mandatory
  • Information regarding a default value
  • Field length or numeric size/precision (both development and test team will want to know)
  • Valid value information (again, supports development and testing)
  • If the values are drawn from a pre-defined value set, information about the source of the values (supports configuration)
  • If the value is derived, details about its derivation (see “Next Time…” at the end of this article)
  • Help Text
  • Example Value(s)

There should be provision for including a layout of the screen for cases where form is an issue at requirements time.

So, with the above details populated in a template an example of an on-line functional detail requirement becomes:

User Story Format:

As a customer, I want to see the details of what I just ordered on-line so that I have confirmation of the order I just submitted with all of its detail.

Shall Statement Format:

The system shall display the details of the order that a customer placed on-line in response to the order having been submitted.

Either format should include acceptance criteria:

Acceptance Criteria – Order Completed Successfully

  • Given a customer placing an order on-line
  • When the customer has completed the order process including confirming the order
  • Then the details of that order are displayed as per the “Customer Order Confirmation Screen” specification found Appendix C.

The first acceptance criteria should be the ‘happy days’ scenario. Subsequent criteria should cover alternate process model paths and exception scenarios (e.g. items with sufficient inventory when added to the shopping cart were out of stock by the time the order was confirmed).

NOTE: The template concept with all of its detail applies to requirements where a whole screen is to be delivered. In cases where there is an existing screen that only requires a small number of changes (e.g. one additional field), a stand-alone detail requirement would be sufficient.

Generic Screen “Look & Feel” Requirements

A classic non-functional requirement is that the application should be ‘easy to use’. This, of course, is next to meaningless and virtually unmeasurable. What is reasonable to require is that the application have a consistent look and feel. Fortunately these days most applications are built on what is called a ‘Framework’. This framework provides generic look & feel functionality that applies to all screens such as:

  • Menu/sub-menu structures
  • Save / Cancel / Undo / Redo Functionality
  • Back / Forward button functionality
  • Searching – filter fields, result list scrolling/paging, column sorting, navigation from selected row
  • Parent / Child screen functionality (e.g. adding a new record or a child line item within a parent)
  • Date field Calendar popup
  • Selectable value field – value list presentation
  • Mandatory Field indication
  • Field validation error display (e.g. where messages appear, how the field in error is identified)

Because the framework applies to all screens within the application it’s unnecessary to include requirements about these capabilities as part of an individual screen requirement. When looking to acquire a package solution the overall look & feel should be considered. If developing an application from scratch, consideration should be given to choosing a good framework to build it on.

Next Time – Detail Requirements For Derived Data

One thing that has only been touched on lightly so far is fields that represent derived data. This applies not only to screens but to reports and interfaces. It also applies to one additional functional area not yet mentioned – batch jobs that generate periodic transactions (e.g. interest payments, period rebates). In those jobs, a value is derived along with a record that represents the context of the value. All to be discussed next time.

NOTE: My current intention is to wrap up this series in the next installment (but follow that with a summary article of the form “N things every BA should know …”). Meanwhile, if I’ve missed out on a topic you feel should have been included in this series, now is the time to add a comment about it.

Requirements in Context Part 6: The Evolution Of Computerized Business Functions

Written by Dan Tasker on . Posted in Articles.

“Those who cannot remember the past are condemned to repeat it.”(1)

This series started with the classic “Swings” cartoon that originated over 40 years ago. I am guessing that the majority of readers of this series were not practicing IT professionals back then. Since I was (just), I thought it worth exploring a slightly different context before getting into the topic of detail functional requirements. In this article we look at computerized business functions from a historical context.

Calculators Supporting Business Functions

In the beginning (around the same time as our swings) there was the four function ‘pocket’ calculator. Those four functions were ADD, SUBTRACT, MULTIPLY, and DIVIDE. Even way back then there was the concept of ‘gold plating.’ Almost immediately after the basic four function calculator was introduced it was superseded by the five function calculator. The fifth function? One near and dear to every business professional – SQUARE ROOT.

Proud new owners of these devices would begin by adding a pair of numbers. They (me included) would immediately perform the same calculation using pencil and paper. This was to confirm that this technological marvel knew what it was doing. This was the earliest recorded example of user acceptance testing. It should be noted that no one ever (and I mean EVER) tested the SQUARE ROOT function. All that mattered was that this function was there. Once this fifth function was available no one wanted to be seen with a calculator that only had four functions.

Related Article: Requirements in Context Part 5: Detail Requirements for Build or Buy

Even with only four (useful) functions, the calculator was, and still is a very useful business tool. The only difference is that business people today don’t buy calculators. They just use the ones that come with their phones, PDAs, and laptops.

Computers vs. Calculators

Many people would be surprised to learn that today’s function-rich computers, at their heart, are only able to add, subtract, multiply and divide. Any more sophisticated mathematical functions like, dare I say, square root, are based on algorithms that utilize those basic four functions.
Ultimately what separates the computers from the basic calculator are two capabilities:

Compare two data items – The ability to test one item against another and know if one is greater than, equal to, or less than the other.

Move data – The ability to move data from one location in memory to another location in memory.

Really. I’m not making this up. That’s pretty much it.

The ability to compare values allows a computer application to go down one instruction path or another depending on the result (or ‘looping back’ to a previous point). What we see at the human level as “If income is greater than expense then …” is an example of something a computer can do that a calculator can’t.

The ability to move data allows the computer to:

  • Receive data from any ‘connected’ input source – from the part of computer memory that received the data from an external source to that part of memory where a function operates on it. Typical input sources are databases, batches of records, real-time input devices and on-line users.
  • Reformat the data within memory – once input data has landed in memory, it’s available to functions that operate on it. Those functions might use it for calculations or for ‘shaping’ it into other formats (e.g. scanned grocery items into purchased items).
  • Deliver data to a ‘connected’ output source – from a location in computer memory that data has been input to or operated on, it is moved to a location associated with a target output device or system. It most likely has undergone some form of realignment to conform to a storage format, or positioned for display on a GUI device.

Just like the four primary math functions have been developed into re-usable higher-level functions, computer languages have developed higher-level ‘compare’ and ‘move’ functions. One example of this evolution is the Sort function. Second and early third-generation programming languages such as Cobol did not include a sort function. When a batch of records about to be processed was required in a particular sequence, they would first be processed by an application (called a sort ‘utility’) that did nothing but move the records around until they were in the designated sequence. Nothing but moving and testing until all was in order.

NOTE: In those early days of sort utilities, developers of applications that read the resulting sorted data would test each record as it was input. This was to ensure that each record was ‘bigger’ than the previous one. Reminiscent of those early pocket calculator adopters manually checking results?

Today’s SQL language is a good example of the evolution of functions to support business processing. That language includes data moving capabilities with its “Order by” and “Group By” clauses, and of course, it utilizes the compare capability with its “Where” clause.

Computer-supported Business Processes

The phrase that is stuck in my head at the moment is, “The more things change, the more they stay the same.” I believe that applies perfectly to where we are today with computer-supported business processes. What has changed are the input and output technologies and computer internal and external storage capacities. But business processes then and now are made up of steps that capture, update, validate, display and calculate data.

NOTE: Another thing that has not changed in all of these years is the diamond shape to represent a point at which a comparison is performed. The more senior readers will remember the original manual version of Visio – the Flowchart Template. For a trip down memory lane (or for younger readers, a trip to the IT museum), I recommend doing a web search on “plastic flow chart template picture”.

Detail Functional Requirements

With this understanding of the fundamental functional capabilities of computers, we return in the next article to the basic theme of this series – Requirements in Context. In particular detail functional requirements.

I leave readers with a challenge – Name a business process or activity that is not fundamentally calculating, comparing and/or moving data. If you think of one, please offer it in a comment below.

(1) George Santayana

Requirements in Context Part 5: Detail Requirements for Build or Buy

Written by Dan Tasker on . Posted in Articles. 1 Comment on Requirements in Context Part 5: Detail Requirements for Build or Buy

The previous article in this series was about keeping the content of high-level requirements (HLRs) at a high level. This article is about the content of detail requirements containing the appropriate amount of detail. We start with a discussion of four delivery contexts, two involving building the solution in-house and two involving purchasing solutions. Examples of requirements are presented using two forms – User Stories and traditional Shall statements. But regardless of form, at the end of the day, content is king.

Build or Buy Contexts

The availability of subject matter experts (SMEs) is a critical factor in sourcing content for detail requirements. For the purpose of this article, we will assume that such people are available. Of equal importance to this deliverable is the consumer of these requirements – those responsible for delivering (i.e. designing, developing and testing) the solution based on the detail. Consider the following delivery contexts:

  • Build – In-house with embedded SME (e.g. full Agile)
  • Build – In-house without embedded SME (e.g. Agile-like, Waterfall)
  • Buy – a custom-built solution (outsourced development)
  • Buy – a package solution (with optional customization)

NOTE: The Build/Buy decision process itself is out of scope of these articles.

Related Article: Requirements in Context Part 4: Keeping High-Level Requirements High-Level

Build – In-house With Embedded SME

What could be better than having the source of detail requirements, an SME, as a full-time member of the development team? Not only that but working on a business information system that can be implemented bit by bit. Personally, I have only experienced Agile-like development. But based on reports from colleagues there are organizations where these conditions exist.

In full Agile environments, whether user stories eliminate the need for detail requirements or they are just considered to be an improved form of requirements, each user story still needs to include content that drives development and guides testing on the way to ‘done.’ From a requirements perspective, the real improvement is that development does not need to wait for a full set of requirements before work begins. Also, the delivery of results into production occurs not long after the requirement has been expressed.

Full marks to this delivery context and the Agile user story form that drives it. But developing and testing has to involve the complete content of what is wanted, so ultimately that content needs to be recorded somewhere (see examples below).

In-house Build Without Embedded SME

I am fresh off a project that utilized Agile-like development. We were given traditional business requirements. Some were high-level, others low-level-ish. As a BA, my role in one of the Scrum teams was ‘pseudo’ product owner. It was my job to interpret selected requirements and write the corresponding user stories and acceptance criteria. Where a requirement was unclear or did not contain sufficient detail, it was necessary to go back to the business requesting clarification.

Besides the problem with requirement content, the overall project was not suited to incremental implementation. At the end of each sprint, teams were able to demonstrate the results of completed stories, but these elements needed to wait many months for a major release of the system.

Functionality being delivered in each major release had to undergo both integration testing and user acceptance testing (UAT). Acceptance criteria from the user stories were of some use to the broader testing efforts, but end-to-end tests had to be developed separately. And because the business users had not been involved with the user stories, they had to come up with their own UAT test cases.

Based on this experience, my conclusion is that the Agile-like context would benefit from detail requirements that contain the most complete content possible. Requirements in either Shall or User Story form can and should include acceptance criteria. This would support any level of testing required.

Buy A Custom-Built Solution

The model of custom-built solutions that I am most familiar with involves the following steps:

  1. The business provides requirements for what is to be delivered and selects a supplier.
  2. The supplier produces a Statement Of Work (SOW) based on the requirements, specifying what they agree to deliver.
  3. The supplier delivers the solution for UAT and bug fixing.
  4. The supplier expects ‘final’ payment and supports warranty period.

My most recent experience involving a supplier was from the business perspective. The development form that the supplier used was Agile. But given that they were relying on client-provided requirements rather than embedded SMEs, they were really only Agile-like. Nor was the detail in their SOW in user story format. The crucial point about this context is that it necessitates the requirements content, regardless of form, to be complete and detailed at the point in time the supplier commits to deliver for a contracted cost.

Buy A Package Solution

Package solutions are almost always a compromise between requiring customization to support the acquiring organization’s current business processes and adjusting the organization’s current business processes to align with what is supported by the package ‘out of the box.’ Any customization required most often is done by the package supplier. If customization is wanted, then requirements for that work falls into the Buy context described above. Even if functional customization is not necessary, there will likely be interfaces and/or reports that need to be developed or customized. Each of these will require detail requirements to support that development. Again it is the content of that detail that is critical, not its form.

So basically regardless of any build or buy context, detail requirements in one form or another are involved – ideally providing unambiguous content. So let’s have a look at what level of detail should be provided for different types of requirements.

Content Detail for Report Requirements

In the previous article the following example of a high-level report requirement was presented:

The system shall support on-line customers being provided with the details of the order that they just placed including a list of items purchased, the amount charged, and expected delivery date in an email so that they have an off-line record of their on-line purchase.

The objective of a Report HLR is to describe it just enough so it is understood in terms of its purpose and value to the overall business information system. During detail requirements, the trick is not to record the detail as a series of individual detail requirements. The detail should ideally be specified in a report template.

A proper report template provides for capturing required information such as frequency, delivery method, and selection criteria. There should be provision for including a layout of the report showing relative placement of headings and labels. Lastly, the template should cater for recording supporting information about the fields seen in the layout. Fields like “Customer Number,” “Transaction Date/Time,” and summary total fields would need little or no explanation. But fields that require special lookup or values derived from other fields should be described, preferably including examples.

With report details recorded in a template-based specification, the detail requirement itself actually can be very simple. The following are examples of how simple a report detail requirement can be when the detailed content is relegated to a specification:

User Story Format:

As a Customer, I want to receive an email containing the details of what I just ordered on-line so that I have an off-line record of my purchase.

Shall Statement Format:

The system shall produce an email to on-line customers upon their submission of each order.

Both requirements should include acceptance criteria:

Acceptance Criteria

  • Given an on-line customer
  • When the customer places an order
  • Then the Customer receives an email that conforms to the “Customer Order Confirmation Email” specification found Appendix C.

While acceptance criteria in the Given/When/Then format has its origins in Agile, there is no reason it can’t be included with Shall statements.

Assuming that all aspects of the report share the same priority, business rationale, and need to be tested together, there is little or no advantage in representing different aspects as separate detail requirements.

Content Detail For Data Requirements

When the scope of a project is known to include new types of data (records and/or fields), ideally it’s good for these to be included as detail data requirements. The previous article had this example data HLR:

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.

From a detail requirements perspective, new record types needed in the business information system should be named and defined. Volume-related estimates are good to have. For new fields (including links to other tables) again business name and definition are useful. For fields, the details of their data type and size should be specified.

Depending on the complexity of the information there may need to be some database design done on the way to a solution. Still, for any new tables and/or fields designers and database administrators need specific information that can only come from an SME. As with reports, the types of information needed about data is common and best served by a Data Definition template.

This again means that all that is needed is a single detail requirement in one form or another. The Shall format example would look like this:

The system shall provide storage for information about Customers as described in the Customer data specification found in Appendix D.

Again, while the above requirement does not appear detailed, the overall information provided (mostly in the template specification) provides what is needed to get the job done. Also like the detail report requirement, if the full content is not provided, when it comes time to design and/or build the data solution an SME will need to be consulted.

Content Detail For Interface Requirements

System interfaces either import data that’s needed by a business information system or else export available data needed by some other system. Where the project scope has identified that information needs to pass between systems, there should be a high-level requirement that represents that need. The example from the HLR article was:

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

From a detail requirements perspective, an SME should know what data items are expected from or by the other system. It should be possible to list those data items based on the existing (or under development) business information system.

If the number of data items is small, they can be listed right in the detail requirement. If larger or complex data structures are involved, the details can be described separately (dare I say using an interface template?). An example in user story form with a self-contained list of interface data items would be:

As the system, I want to receive daily currency exchange rate data from the European Central Bank so that I can convert purchase amounts from a supplier currency to a customer’s preferred currency.

Acceptance Criteria

  • Given access to base exchange rates made available from European Central Bank
  • When the ECB exchange service makes new rates available
  • Then the following details about each currency is recorded and available for use converting between currency pairs:
    • To Currency E.g. USD
    • Effective Date
    • Exchange Rate From Euro E.g. 0.89
    • Rate Type E.g. Mid-Market

Data items in an interface list should include details such as attribute name, description, and examples. The objective is to support the subsequent ‘mapping’ of corresponding items on each side of the interface during the interface development phase, where field details of size and type can be addressed. This technical mapping is done by someone familiar with the business information system’s database schema. That person will also need access to the external system’s interface specification.

Upcoming Articles

This article included discussions of content for Report, Data and Interface requirements. The two requirement types that were not addressed were Functional and Non-Functional. Types of Non-Functional requirements are each very different and the detail content will not be covered in this series. But detail functional requirements are so important that the next two articles are devoted to them (including adding Use Cases to the mix of possible forms of representing detail). Stay tuned.