Skip to main content

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.