See discussions, stats, and author profiles for this publication at: https://www.researchgate.

net/publication/328492160

High-level Functional System Requirements

Technical Report · September 2018

DOI: 10.13140/RG.2.2.13738.06080

CITATIONS READS

0 718

1 author:

Larry Lee
SiFive
5 PUBLICATIONS 0 CITATIONS

SEE PROFILE

All content following this page was uploaded by Larry Lee on 24 October 2018.

The user has requested enhancement of the downloaded file.

 High-level Functional System Requirements

Nolij Consulting

September 19, 2018

Abstract

In this article, we define high-level functional system requirements,

describe their role within the software development process, and present
practical recommendations for their development, documentation, and
use.

1 Introduction

“Requirements” is an ambiguous term whose meaning frequently changes de-

pending on the context. Colloquially, developers speak of “high-level” and “low-
level” requirements without ever clarifying the distinction between them.

So what are the different types of requirements, and how do they fit within
the larger software development process? In this report, we give a definition
for high-level functional requirements and describe how they relate to system
business cases and the broader software development process. We describe how
to document these requirements using the user story format and explain how
requirements documented in this way are used by designers. We then explain
how system designers produce the system specifications that developers com-
monly refer to as “low-level” specifications, and present a simple scheme for
categorizing them.

1
2 High Level Functional Requirements

A Business Case is a document that:

1. describes a system to be built

2. describes the functionality that the system will provide

3. explains how this functionality supports an organization’s objectives

4. and analyzes the costs, benefits, and risks associated with building the
system.

Every software project should start with a business case. This document serves
to identify the outcomes produced by the system, and explains the relationship
between these outcomes and an organization’s objectives.

In describing the outcomes that a system will produce, the business case should
identify the system’s users - i.e. the system’s “target audiences” - and describe
one or more interactions between the system and audience members. Each in-
teraction description should specify four things: the interaction’s audience, the
interaction, the outcome produced by the interaction, and the relative impor-
tance of the interaction.

These descriptions are similar to the user stories used in Agile, and are fre-
quently referred to as user stories. However, we distinguish these interaction
descriptions from user stories because they have two distinguishing character-
istics. First, the interaction descriptions provided by a business case should
describe the interactions between users and the system as a whole - i.e. they
should not describe interactions between users and components of the system.1
Second, each interaction description should be related directly to the organi-
zation’s mission and objectives. This constraint does not apply to user stories
generally.

These interaction descriptions are examples of “high-level functional system

requirements”. These requirements specify “what” outcomes a system must
produce. They should not proscribe “how.” During the design phase, system
architects, designers, and developers identify design solutions that produce the
required effects.

1 Doing so would effectively proscribe a structure to the system, which should be developed

during the design phase.

2
In an Agile environment, we recommend that product owners work with product
stakeholders to define these high-level functional requirements. In doings so,
we recommend that they first identify the system’s target audiences. Then
enumerate the goals that members of these groups have when interacting with
the system, and the goals that the organization have when interacting with
these groups through the system. If these interactions involve communicating
information, we recommend that they also describe the content involved.

We recommend that the product owner and stakeholders use a lightweight for-
mat to document these interactions. We endorse the format proposed by Mike
Cohn [1]: ”As a <type of user>, I want <some goal> so that <some reason>.”
For example, ”As an HHS employee, I want to find a subsidized childcare
provider.” Additionally, the description should include some measure of the
relative importance of the given interaction relative to others.

3 The software development process

Software development activities can be classified under five general categories:

requirements analysis, design, implementation, testing, and integration/ deploy-
ment.

Requirements analysis activities are those activities in which the development

team works to clarify, revise, and prioritize requirements. Design activities are
those activities in which the system is described in terms of a set of functional
components whose operations and interactions provide the required features and
functionality. Implementation activities are those activities in which software
developers model these components in source code. Testing activities, are those
activities in which this implementation is compared against its design specifi-
cation to identify any discrepancies2 . Integration/deployment activities refer
to those activities in which components are added to a system or brought into
production.

In Agile, all of these activities are performed within each Sprint cycle. Each
sprint cycle begins with a sprint planning and backlog grooming phase that in-
cludes requirements analysis. The implementation phase within a sprint encom-
passes both design and implementation activities. Finally integration/deployment
activities occur during the Sprint demo and retrospective phases.

2 IEEE distinguishes between verification and validation activities. Briefly, verification

ensures that a system matches its specifications whereas validation ensures that the system
can fulfill its intended purpose.

3
4 Design

Design activities are those activities in which system designers describe a set of
components that collectively comprise the system, and provide the features and
functionality specified in the high-level functional system requirements.

For example, given the high-level functional requirement presented above, a

designer may introduce a map feature showing the location of various childcare
providers along with their contact information, availability, and price ranges.
This component provides the information and functionality needed for users to
quickly fulfill the goal documented in the given user story.

Every component has three aspects: some body of content that it generates, ma-
nipulates, or communicates; some behavior; and some interface through which
it interacts with users, the rest of the system, and its environment.

For our example map feature, the content communicated through the feature
is some collection of childcare provider records. These records must include
contact and location data. The component’s behavior includes all of the actions
that the feature can perform. For example, the map may allow users to zoom
in and out, or filter providers by price and availability. Finally the component’s
interface includes its visual appearance, but may also include other interfaces
as well.

5 Specification

When designing components, designers must specify the content processed by

the component, its behavior, its interface, and the constraints imposed on each.
These must be documented and communicated to the developers that will be
responsible for implementing the given component.

In Agile, these behavioral specifications (also called “functional specifications”)

are commonly documented as user stories. User interface specifications are
typically communicated through visual mockups. Content specifications are
typically documented using information architecture documents.

We recommend that designers document behavioral specifications using Gherkin

- the specification language used by Cucumber. This format, allows designers
to specify more complex behaviors than the user story format proposed by Mike
Cohn while still remaining lightweight.

Below we present an example functional specification for the map feature in

Gherkin:

4
Feature: Childcare Provider Map

Scenario: Initial Load

When the map loads
Then for every child care provider, x, the map displays a
map pin positioned at x’s location.

Scenario: Pin Click

When the user clicks on a map pin
Then the map displays an overlay presenting the name, phone
number, and price of the child care provider
represented by the pin.

Scenario: Overlay Close

When the user clicks on the overlay close button
Then the overlay window closes revealing the provider map.

Importantly, visual design specifications must include detailed constraints such

as font family, font size, margins, and padding widths. Numerous tools ex-
ist to provide visual mockups that include these specification details. We can
recommend Zeplin and InVision as viable design tools.

It’s important that development teams, maintain an inventory of the high-level

functional requirements, the designed components that comprise the system,
and the specifications for these components. This repository should link com-
ponent specifications to high-level functional requirements so that the team can
ensure that all of these requirements are covered by a design solution, and to
ensure that the design team can anticipate the impact of any design changes on
these high-level requirements.

6 Implementation

Before a developer can begin implementing a system component, they must

have a detailed description of the component. This description is provided by
the component specification provided by the designers.

We recommend tracking all development tasks using JIRA tickets but discourage
the practice of using JIRA tickets to document design specifications. Instead
we recommend that teams document specifications separately and link to these
documents from JIRA tickets.

All source code should be placed under version control. We have found it useful

5
 to preface all source code version commits with the name of the associated ticket.
This practice makes it easy to link source code to specific feature requests and
system components.

7 Testing

Implementation activities should produce an implementation. An implementa-

tion consists of a canonical representation of the system. This may be a collec-
tion of source code files, a configuration profile, etc. Testing involves comparing
the implementation against its specifications and identifying any discrepancies
between them.

To test a system, testers must be provided with both an implementation and

specifications for the system. The testers should develop a test plan that identi-
fies the specific actions that testers will use to verify each of the properties and
constraints described in the system specifications. The purpose for document-
ing the tests that will be performed, and the specific properties being tested, is
to ensure sufficient coverage during testing and to ensure that this coverage is
maintained with each test iteration.

8 Conclusion

In this report, we have described high-level functional requirements and ex-

plained their role within the software development process. We have given
recommendations describing their documentation and communication. The dis-
tinction between high-level functional requirements and component specifica-
tions is important, and we’ve discussed the relationship between them. In clos-
ing, high-level functional requirements capture “what” a system must do to
further an organization’s missions and objectives. Designs specify “how,” and
design specifications describe the constraints that must be satisfied in doing so.

References
[1] Cohn, Mike, User Stories Applied: For Agile Software Development Ad-
dison Wesley Longman Publishing Co., Inc., 2004.

View publication stats