Writing functional requirements is one of the main tasks, often the main task, of a business analyst. Traditionally it has often not been done very well. This article explores five tried and tested approaches to improving things.

This article follow on from the two others,

• What is a requirement?
• What is a functional requirement?

You may like to read these before continuing.

Estimated reading time: 18 minutes

What’s the problem?

Before writing anything, make sure that the stakeholders agree on what the problem is.

• State the impact of the problem
  • What issues is it causing?
  • How much is it costing?
    • How much is a solution worth?
  • Are there any related problems?
• Identify the stakeholders who are affected by the problem
  • In what way are they affected?
  • These are the people who need the requirement
    • Engage with them to understand their issues and their work
    • How will they benefit from a solution to the problem?
    • How will the organisation benefit from a solution?
• Summarise the above as a case for achieving the requirement

Recap of the essential elements of a functional requirement

We have known for decades what a requirement must include, ie,

• Required action/function
• Role of the person, the ‘user’ or ‘stakeholder’, that needs the function defined by the requirement
• Rationale: Why the requirement is needed
  • This relates to one or more aspects of the problem
• Acceptance criteria: Tests that can be applied to the product, e.g. a software application, that implements the requirement
  • These tests will see if the product meets user expectations and demands
  • Remember that if it is impossible to test your ‘requirement’, then it is not a requirement

Ways of writing a requirement to include the essential elements

There are a number of ways of expressing the information that forms the requirement. We’ll look at and compare five popular ones. Specifically, we will look at,

• Traditional text, sometimes referred to as ‘atomic’ requirements
• Task description as a requirement
• Use cases
• User stories
• Decision tables

We will also consider how requirements identify data and business rules.

Approach 1 – Writing requirements as traditional text statements

The most commonly accepted form for traditional requirements is,

• “The ‘user role’ shall be able to (perform function x)”

For example,

• The hotel receptionist (user role) shall be able to check in a guest (function)
• The agent (user role) shall be able to check in a passenger”
• The system shall enable check in agents to check in passengers”

Atomic requirements

The above form of requirement was sometimes called, ‘atomic’, because it was considered that the requirement could not be made simpler/smaller and remain meaningful.

Problems with atomic requirements

• The ‘atomic’ requirement approach can result in lots of tiny requirements
  • I have seen business analysts create thousands of such requirements for a system
• It can be hard to show how an atomic requirement will solve the problem
  • A solution might a set of related requirements

• Without diagrams, such as a business process model, it is hard to visualise the big picture and the context for the requirement
  • The expression, ‘Can’t see the wood for the trees’, is often quoted
• Lacking context, e.g. a diagram, developers may not understand what is meant by a particular requirement
  • This problem is made worse if regular discussions between requirements writers, stakeholders, and developers are not possible
    • This can happen with the way that some approaches to software development, e.g. ‘waterfall’, are applied
• It can be hard to,
  • Check for completeness and omissions
  • Tell if a requirement is in scope for the intended system
  • Identify links between requirements
  • Assess the impact of a change to a requirement
• It is difficult and time consuming for business stakeholders to review a large set of atomic requirements with no context

Hierarchy of atomic requirements

A common approach to revealing the overall structure of a set of atomic requirements is to write them in a hierarchy. Start at a ‘high’ level, perhaps equivalent to a business process or one of its component tasks, the requirements are progressively ‘decomposed’, i.e., broken down into smaller statements, e.g.

• Requirement 1
  • Requirement 1.1
    • Requirement 1.1.1
    • Requirement 1.1.2
    • ….
  • Requirement 1.2
  • ….

Acceptance Criteria/Testing with atomic requirements

• It is easy to create acceptance criteria and test cases for each atomic requirement
• It can be hard to test the system as a whole

Specifying the rationale for a requirement in traditional approaches

• The rationale in ‘traditional’ approaches to writing requirements, is normally written separately from the requirement itself
• It might be hard to state a rationale if the requirement is very small, i.e. if the requirement is not seen as part of a useful unit of business functionality

Grouping atomic requirements

It is useful to group related sets of atomic requirements so they can be mapped to recognisable business activities.

Mapping atomic requirements to business tasks

The following ‘atomic’ requirements are related to tasks associated with the reception and provision of services in a hotel, as shown in the diagram, ‘Tasks and user roles in a swimlane diagram’.

• A hotel receptionist (user role) shall be able to check-in a guest (function)
• A hotel receptionist (user role) shall be able to check out a guest
• A team member shall be able take an order for a meal

Requirements can be cross referenced to process models. The models give context to the requirements. They also help to explain the rationale for a requirement. For example, a requirement can be shown to support a vital part of the process.

Example – Linking atomic requirements to tasks and task steps

Tasks in a business process model consist of task steps. When using the ‘atomic’ approach to writing requirements, people often write their requirements at the task step level, e.g.

• Task – Check in guest
  • Task step – ‘The receptionist retrieves/views the booking’
    • Atomic requirement – ‘The receptionist shall be able to retrieve/view the booking’
  • Task step – The receptionist records guest arrival
    • Atomic requirement – ‘The receptionist shall be able to record the guest arrival
• Task – Check out guest
  • Task step – ‘The receptionist prints the bill’
    • Atomic requirement – ‘The receptionist shall be able to print the bill’
  • Task step – The receptionist records the payment
    • Atomic requirement – ‘The receptionist shall be able to record a payment’
• etc.

This leads us to approach 2 for writing functional requirements.

Approach 2 – Writing functional requirements as task descriptions

We can see that some of the problems associated with ‘Approach 1’ can be avoided if the atomic requirements are presented in the context of a business process and its tasks.

Going one step further, the atomic requirement form can be replaced with a

• Business process model, e.g. a swimlane diagram
• The set of tasks in the process
• Task descriptions, e.g.
  • The steps for each task
  • Other useful information
• Data created and used
• Business rules that constrain or control the process

This approach was identified by Soren Lauesen in his landmark book, Software Requirements, Styles and Techniques’.

Writing task descriptions

There are a number of ways of writing a task description, e.g.

• Scenarios
• Decision tables

Scenarios

Business processes consist of related activities/tasks. Activities/Tasks consist of sets of related steps.

Main scenario

There is usually a combination of tasks in a process and steps in a task that are considered to be the norm. I.E, it is the situation that occurs most frequently. This situation is referred to as the main scenario.

Alternative scenarios

Alternative scenarios represent different situations that can arise. For example,

• Checking members of a tour group into the hotel
• Upselling rooms to a customer
• Offering alternative room types if the required one is not in stock

Alternative scenarios also arise due to error situations. For example, a hotel might have overbooked resulting in insufficient rooms for everyone who has a valid booking.

Creating scenarios

Scenarios may be captured in text or as flowcharts, e.g. UML activity diagrams.

Scenarios can be identified and defined in workshops involving business analysts, product owners, business stakeholders, and developers. Agile approaches encourage collaboration between representatives from all parties, the entire ‘team’. The results can be objectively reviewed by other subject matter experts who were not involved in the workshops.

The aim of the requirements writers is that the full set of scenarios shall collectively describe a wide variety of situations that the business process and its tasks must be able to handle. Note that we should not try to identify the complete set of scenarios immediately. They gradually surface in discussions between all parties. It is probably impossible to anticipate every way in which an error might occur.

Elements of a requirement in the business process approach to functional requirements

The business process/task approach captures all elements of a requirement, i.e.

• User role
  • Each swimlane is dedicated to one role and the tasks performed by that role
• Function
  • The task describes the function.
• Rationale
  • The value of a task to the overall process provides the rationale for the associated requirement
• Acceptance criteria
  • The scenarios can be the basis of acceptance criteria (tests) to validate the finished system product, i.e.
    • Can it perform every identified scenario?
    • Can the user confirm that this is really what they want?

Scenarios might be considered as the essential ingredient in any form of requirement.

Advantages of associating functional requirements with business activities

Common challenges in defining requirements include:

• Duplication, i.e. including the same requirement more than once
  • This can be hard to spot if there are large number of atomic requirements
• Omission, i.e. the requirement is missed and not recorded
  • As with duplication, this can be hard to spot
• Ambiguity, i.e. the requirement can be interpreted in more than one way
• Lack of context, i.e. failure to understand the bigger picture

These problems are much easier to avoid when the requirement is defined in the context of a task/activity that is part of a business process. The requirements writers, in cooperation with the business stakeholders, should also feel free to include diagrams, tables, examples, and simple prototypes to help clarify their intentions. These things also serve to encourage discussion.

Approach 3 – Use cases

What is a use case?

A use case represents a goal or objective for a user. It is an effective means of illustrating a functional requirement.

Unified Modelling Language (UML)

Use cases were originally included in the specification for UML, ‘Unified Modelling Language’. The UML standard is publicly available and is maintained by the Object Management Group (OMG).

Use cases support business tasks

The diagram, ‘Tasks and Use Cases’ has two levels:

• Level 1 shows the business tasks
• Level 2 shows examples of requirements, illustrated as use cases
  • A use case typically relates to an IT application that supports a business task

Note that,

• The tasks flow in a sequence
• Use cases are one off activities, normally triggered once for each occurrence of a task

Use case diagrams

Use case diagrams feature,

• The user role, known as the actor
  • Often shown as a stick person
  • The UML specification allows any icon to be used to represent actors
• The required function
  • This is the use case itself
  • It is drawn as an oval containing the use case name in verb-noun format, e.g.
    • Check in a guest
      • Check in (verb) – A guest (noun)
• The context in which the use case or set of use cases operate
  • This is shown as a rectangle containing the name of the ‘system’
    • Actors are placed outside the rectangle
    • Use cases are placed inside the rectangle
    • A line, the ‘association’, connecting actor to use case crosses an edge of the rectangle

Detail of a use case

It is important to understand that the UML standard for use cases simply defines their components and gives examples of use case diagrams. It does not say how to write the details of the use case. Perhaps because of this, many individuals and groups have jumped in with their proposals, some of which can be overly complex.

The result of this is that many people, e.g. many in the agile community, have rejected use cases on the grounds that they are too complex. They are only complex if the writer chooses to make them so. The UML specification comments that, ‘Use cases are typically specified in various idiosyncratic formats‘.

The detail of a use case, i.e. the functionality, can usually be written as a set of scenarios. If the use case involves multiple decisions or business rules, a decision table may be a better option. The scenarios can form the basis for the acceptance criteria.

Use cases and system testing

Use case scenarios are an excellent basis for creating test cases. They can passed to a specialist test team or worked on by a team of generalising specialists.

Mini course on an ‘agile approach to use cases’

Click here for a free mini course on use cases.

Approach 4 – Writing functional requirements as ‘User stories’

Elements of a user story

A user story contains three of the essential elements of a requirement in a single sentence.

Example of a user story

• As a booking clerk (User role)
• I need to create a booking for a guest (Function)
• So that, (Rationale), e.g.
  • A room can be reserved for a particular person on a particular date
  • All expected guests can be checked into their rooms
  • No shows can be identified
  • …

Acceptance criteria for a user story

Detailed acceptance criteria can support the story. One way of writing acceptance criteria is in the form of scenarios. We can see that the scenario is a common factor in the various approaches to defining functional requirements.

User stories in agile approaches to developing IT systems

Use stories, or simply, stories, have become very popular in agile approaches to the development of IT systems and other products.

Approaches writing to user stories

Various approaches to user stories have evolved. You might start to get into the discussion with the book, ‘User Stories Applied’, by Mike Cohn, founder member of the Agile Alliance.

Encouraging discussion

User stories are intended to encourage discussions between business stakeholders and the members of the development team(s). Teams can decide for themselves the best way of recording these discussions.

Why user stories?

ASs mentioned earlier, the elements of a well formed requirement were recognised decades ago, so what is the benefit of the user story technique?

A story captures the essential elements of a requirement in one easily formed sentence. Detail can be added as acceptance criteria. Acceptance criteria can be written as scenarios. So user stories are a neat way of packaging requirements.

Both users and developers seem to like them. They can be effective in promoting discussions that capture a collective view point.

In my opinion, the same things can be true of use cases. Perhaps use cases were too often written in over complex ways. I have seen real life examples that covered fifteen pages of printed text. That might have been ok if the text was grouped into scenarios. What I saw, usually wasn’t. This made it difficult for everyone.

Unlike use cases, user stories do not have a standard diagram. A use case diagram offers a focal point for workshops to identify stakeholder roles that need to specify user stories. The workshop members can agree on the scope of the system and ensure that all relevant business representatives have been included.

Approach 5 – Decision tables

Decision tables are an ideal approach for situations where there are many related conditions. They are also valuable for documenting business rules. See this post for details.

Conditions are usually shown as ‘IF’ or ‘WHEN’ statements in task descriptions, e.g.

• IF order price is greater than £1,000.00
  • THEN apply a discount of 5 %
• WHEN the order value is greater than, …

For business analysts who were unsure how to best document situations with many conditions, i.e. many IF/WHEN statements, decision tables were often seen as an epiphany, i.e. an eye opener.

In the past, some BAs have told me that they thought requirements must always be written as text. The vital thing with requirements is that they clearly and simply express users’ demands and can be understood by the people who will build the products that satisfy those demands. BAs should feel free to use whatever is necessary to achieve those goals, e.g. text, diagrams, pictures, examples, tables, and, very importantly, discussions.

More elements that can be linked to a requirement

Data

A scenario can identify the data needed for the function. It is useful to have a common data model and/or database schema with agreed definitions of all data. These data definitions are maintained by a central body rather than independently, by each project team. Such an approach has the following advantages:

• Ensures consistency of data definitions and understanding
• Removes the need for each project to maintain its own view of the data
  • Reduces the team’s workload
• Reduces the size of each requirement/task description
• Speeds up development
• Supports reuse of requirements
• Reduces cost of maintaining the requirements
• Shared data definitions can help to increase their quality
  • The more people that see the definition, the more chance there is that errors will be spotted

The task description/requirement can cross refer to these common data definitions, thereby simplifying the requirement itself. Including data definitions in the requirement itself has several disadvantages, e.g.

• The requirement becomes larger than necessary
• If data changes, the requirement has to change

Data models might be created in business terms rather than the terms used in the technical design of the database. Such ‘business data’ can be used before the design of a data base.

Business models and technical models can exist in shared repositories. This encourages everyone to use the same names, formats and definitions. Maintaining the data definitions centrally provides better control for ensuring the integrity of the data.

Process models and data

BPMN, UML Activity Diagrams and Data Flow Diagrams all support the identification of data used by a process.

Business rules

Remember that business rules are not requirements. Business rules represent policies that apply across an organisation. Unlike requirements, they are not specifically associated with particular projects.

Requirements can cross refer to these ‘globally defined’ business rules.

Some rules can be cross referrenced in models of business processes and data. This works well with approach 2 to writing functional requirements, where a requirement is the implementation of a business activity, i.e., my requirement is to have a business activity as defined in the scenarios for this business process/activity. The rules themselves can be implemented in the operational processes and databases. Requirements can refer to the rules in these contexts.

Similarly to databases, business rules can be held in centralised stores, often referred to as repositories. Systems that implement business processes can be linked to such repositories so that the rules dynamically affect the behaviour and routing of the process.

Writing functional requirements in an Agile environment

Placeholders

Requirements in agile, typically in the form of user stories, can initially be specified as placeholders, i.e. with the minimum amount of detail. Detail is usually left until shortly before development, sometimes described as, ‘The last responsible moment’. This should avoid, or at least minimise, the risk of spending resources on something that may never be developed into a finished product.

What to exclude when writing functional requirements

Constraints

It is important to separate the list of a product’s functional requirements from the constraints imposed by the business and technical environments in which the product will operate.

Constraints can be on things such as,

• Time
• Money
• The environment in which the product will run
• Standards

Many of the constraints will be known at the outset of the project, before the functional requirements have been identified.

Project management

Project management, whether performed by a dedicated project manager or by the team that is creating the product, is concerned with things such as,

• Planning the order in which to develop and implement functions and features
• Estimating time scales
• Managing budgets and timescales.

Such concerns might cause the team to drop, delay or simplify a function or feature.

It is best to separate these concerns from the description of the essential requirement.

Requirement priority

The priority, i.e. its relative importance when compared to other requirements, does not form part of its core description. That is, the priority does not describe a product or its functions and features.

The purpose of a priority is to help agree on the order in which functions should be built from the requirements. It’s a tool for project management. Priorities can, and probably will, change as a project progresses.

The business stakeholders may of course discover at some point that they don’t need the function specified by the requirement; it can then be dropped. They may also change their minds about

• The detail of a requirement
• Exactly what the required function needs do

However, changing the priority does not change the requirement itself

Requirements can be allowed to evolve. This is a feature of iterative approaches such as agile.

Functional requirements and solutions

There will always be more than one way to design a product that can perform the required functions, i.e. there can be many solutions for a single requirement.

Remember that system designers must take account of the non functional requirements and the constraints, as well as the functional requirements.

Impact of the users on how functional requirements are written

The descriptions of the required functionality must be understandable by everyone with any of the following roles and responsibilities:

• Developers
  • Developers build a product that can perform the required functions within given constraints and non functional requirements.
• Purchasers of ready made systems/applications that can perform the required functions
• Business stakeholder(s):
  • Confirm that the team has correctly identified the business problem
  • Confirm that the proposed will solve (or help to solve) the business problem
  • Provide the money to pay for the app
• Users
  • Use one or more of the system’s functions
• Testers 
  • Test the product to ensure that the requirements have been correctly implemented

Representatives of the above roles must work together to confirm that the proposed requirements are correct.

Later in the project they must help to add detail to the requirements and to test the implemented system.

Recommended reading

Soren Lauesen

• Software Requirements Styles and Techniques

Karl Weigers

• Software Requirements

Robertsons

• Mastering the requirements process

Mike Cohn

• User Stories Applied – For Agile Software Development