PMI Sites
Register
Disciplined Agile
Search

    Practice: Capturing Functional Requirements

    Note: Disciplined Agile distinguishes between different requirement types. This article focuses only on the functional requirements format.

    Functional requirements can be captured using many different formats. In most cases, the user story format is most suitable and is most commonly used today.

    This article describes how to use the user story format. It also offers guidelines for choosing the alternative format of use case. These two formats are not mutually exclusive and can be used to complement each other.

    Why to Do This Practice

    For purposes of decomposition, epics are used together with user stories to capture functional requirements at a higher level than individual user stories.

    Functional requirements don’t stand in isolation; they exist in the context of higher-level requirements such as features or minimum business increments. Features and MBIs are outside of the scope of this article because as they are usually out of sight of the development team.

    For a more detailed discussion about functional requirements formats and for guidance in choosing a format, please see the Explore Usage decision point in Disciplined Agile.

    Who Does This Practice

    The product owner is responsible for capturing and managing the functional requirements. They collaborate with business stakeholders, to understand business value, and the development team, to convey and collaborate on requirements details. In essence they act as the conduit between the business and the development team, and epics, user stories and use cases are their means of communication.

    The requirements format is sometimes mandated by the organization. Sometimes, it can be selected on a per-project or per-team basis.

    What to Do

    Inputs

    Inputs to this practice include:

    • Product backlog with higher-level requirements to be decomposed including features and MBIs
    • Corporate guidelines

    Approach

    There are two approaches for capturing functional requirements: User stories and epics, and use cases. They can be used together.

    User Stories and Epics

    User stories and epics are closely related and are often used together.

    Epics capture functional requirements at a high level, which are then decomposed into user stories. Epics are used to capture high-level requirements early in the “discovery process” such as during Inception.

    User stories help capture and support discussion about details within epics.

    Epics and user stories use a similar format. The difference is in the level of abstraction; while the entire scope of a domain can be captured with a manageable number of epics, user stories within each provide details such that development teams can implement them.

    Epics and user stories support planning well. A strategic overall product roadmap can be defined with epics, and iterations can be planned in terms of user stories.

    User stories are called this for a reason: they describe functionality from the perspective of a user, and they are expressed in the form of a “story.” The underlying idea is to provide a “light representation that invites a conversation.”

    User stories evolve in degree of completeness, starting as just a sentence or two describing what the user wants, to being complemented with more elaborate details and acceptance criteria as the story nears implementation. This approach creates a lightweight overall requirement capture process that aligns well with the iterative and incremental life cycle.

    Use Cases

    Use cases were first popularized in large-scale software development endeavours as an alternative to traditional software requirements specifications and other older requirement formats. They offered a format and process that allowed them to be integrated in the iterative and incremental development processes that emerged at the time.

    While residing at a similar level of abstraction as epics, use cases can be more elaborate and include additional properties such as alternate paths to achieving the goal, exceptional paths, pre- and post-conditions.

    Using User Stories and Use Cases Together

    Just like epics, use cases are used to map out the functionality of a whole domain, but in a much more elaborate (and rigid) format.

    Complementing use cases with user stories to fill in the gaps helps keep the use cases limited to only the essential information while leaving the details to be captured with user stories.

    Process Goals

    Disciplined Agile® Delivery (DAD) describes process goals to help with capturing functional requirements:

    Tools and Techniques

    Tools do not usually influence which requirements format to use. However, tools can help visualize the context of a given requirement. This in turn can suggest what information needs to be recorded in the requirement. Consider a mind-mapping tool or a drawing tool that can be used to draw flow, and other relationship diagrams.

    Story Maps

    Story maps help provide a visual overview of user stories in terms of which epic they belong to and which iteration they are allocated to. Visualizing the organization of user stories with story maps help facilitate prioritizing and sequencing of user stories.

    General Template: User Story

    The essential attributes of a requirement written in the user story format are:

    • ID. An identifier used to refer to the story.
    • Description. The intent of the story. Here is the most-common template:
      As a <user>, I want <some goal> so that I get <business value or functionality>
       where:

    “<user>” means the role played by the person to whom the new value will be delivered. For instance, “As a bank teller,” might begin a user story for a software capability that eases an aspect of the teller’s work

    “<some goal>” means what the system will do for the user. For instance, “I want to be able to scan in my customer’s debit card number”
    “<business value or functionality>” means what the new capability does for the user. For instance, “so that I eliminate the time typing in numbers as well as redoing an entry because of a typing mistake; I currently spend an average of two minutes extra work on each transaction because of these activities.”

    • Validation strategy. Every story must have criteria so that the team can know, “Is this story done?”
    • Parent and related stories. Where did the story come from and what else is it related to?

    General Template: Use Case

    The use case format is one of the main alternative formats used for requirements.

    Use cases are best for when more detailed information is needed about how the stakeholders will need to interact with the functionality being added to the system. This can include things like the before and after conditions of the system fulfilling the requirement, alternative and essential actions based on differing conditions when the user invokes the functionality in the requirement, etc.

    Use cases are most commonly used to describe system capabilities but can also be used to express business or stakeholder goals (these are sometimes called “business use cases”).

    The “Fully Dressed” use case format, based on the work of Alistair Cockburn, is:

    • Title: “an active-verb goal phrase that names the goal of the primary actor”
    • Primary actor: can be a user, or another system
    • Goal in context: statement of the requirement’s goal and the conditions around the system when its functionality is invoked
    • Scope: of the system into which the Use Case is being implemented
    • Level: of abstraction of the “goal” or requirement
    • Stakeholders and Interests
    • Precondition: assumed condition of the systems around the target system
    • Minimal guarantees: critical interests protected in any situation
    • Success guarantees: state of the world around the target system, if the goal is achieved
    • Trigger: event that kicks off the Use Case
    • Main success scenario: interactions between primary actor and target system, from trigger to goal
    • Exceptions: what to do when the steps in the scenario are interrupted
    • Extensions: additions to the steps in the scenario, for different conditions than assumed in the main success scenario
    • Technology & Data Variations List: step variations
    • Tabular: When there are a number of different conditions and outcomes, that are naturally represented in table form
    • Graphic: When the desired outcome is hard to describe with words, but easy to illustrate with graphics

    The main danger in the use case format is in making implementation decisions earlier in the development process than they are needed. For instance, it is tempting to specify the steps of interaction between the primary actor and the system prematurely in too much detail.

    Use cases are intended to evolve incrementally, making them gradually more complete as they are nearing implementation. Another danger is to not understand what amount of information is enough at any given point of the use case’s lifecycle, and instead attempt to make them complete from the outset.

    Outputs

    Output from this practice is well-formed and informative requirements that facilitate the implementation work of the development team.

    When to Do This Practice

    At every level of requirements decomposition.

    Outcomes

    Following this practice will improve the quality of requirements. Such requirements will:

    • Introduce detail and decisions only as needed
    • Contain all the information needed at each stage, and only that information
    • Avoid constraining the implementation prematurely, before all the information needed to make decisions is known 

    Product Owner Overview