When a mechanical engineer specifies a length of 12 centimetres, it is perfectly clear what is required. When an electrical engineer specifies a current of 2 amps, once again is perfectly clear what is needed. But when a software engineer or business analyst specifies a feature, the underlying need is often lost in a debate about the best way to describe software features.
This is because they don't have a standard approach for describing software features. In the absence of a standard, various competing approaches have been 'invented' to fill the void.
For example, a feature of a Hotel Management System could be described as a user story:
  • As a call centre operator, I want to be able to enter a new accommodation reservation so that the guest is guaranteed a room and the hotel can estimate its future occupancy rate

or maybe as a use case:
  • The call centre operator uses the hotel management system to enter a new accommodation reservation

or possibly with a diagram:


or even as a formal requirements statement:
  • The system must provide the ability to enter a new accommodation reservation

Although describing the same feature, each style has pros and cons and captures a different set of information.

In an earlier article Describing Software Features I introduced a simple verb-noun template to describe software features using natural language:
  • Enter new accommodation reservation
  • Amend existing accommodation reservation
  • Manually cancel duplicate accommodation reservation
  • Automatically cancel accommodation reservation if the guest is a no-show
  • Automatically add provisional accommodation charge at 2am each day
  • Periodically list overseas guests that checked in last week

In this article, I am going to compare popular approaches for describing software features and show how the verb-noun template can be extended to become a universal template for describing software features.

User Stories
User Stories have been around since the late 1990s with various people expanding and clarifying the approach over time. There's no universally accepted definition for a user story, but many suggest that Mike Cohn's 2004 book, User Stories Applied: For Agile Software Development is the standard reference for the approach:

A user story describes functionality that will be valuable to either a user or a purchaser of a system or software.

In my original article, I showed how a feature described using the verb-noun template can be converted into a user story by simply inserting it into the standard user story template.

As a {role} I want to be able to {feature} so that {reason or benefit}.

The hotel management features listed above can be re-written as user stories:
  • As a call centre operator, I want to be able to enter a new accommodation reservation so that the guest is guaranteed a room and the hotel can estimate its future occupancy rate
  • As a call centre operator, I want to be able to amend an existing accommodation reservation to accommodate guests who change their plans
  • As a front desk clerk , I want to be able to amend an existing accommodation reservation so that I can upgrade guests when the hotel has a lot of available rooms
  • As a call centre operator, I want to be able to manually cancel duplicate accommodation reservations so that the hotel's room capacity is not artificially reduced
  • As a front desk clerk, I want the system to automatically cancel an accommodation reservation if the guest is a no-show so that the rooms are immediately made available for future reservations and walk-in guests
  • As a back office clerk, I want the system to automatically add provisional accommodation charge at 2am each day to ensure the bill is accurate and reduce my workload
  • As a front desk clerk, I want to be able to periodically list overseas guests that checked in last week so that (can't think of any good reason so why do we need it!!!)

Notice how the amend an existing reservation feature is used by both the Call Centre Operator and the Front Desk Clerk but for different reasons.

Also notice how the reason or benefit justifies a feature and provides a link to the underlying business need. Except of course, in the case of the last feature.

A subtle aspect of user stories, which doesn't seem to get much attention, is that a user story role can be viewed from two different perspectives.

The obvious perspective of the role is to identify the user that uses the feature. For example, a hotel Guest who uses a self check in kiosk in the hotel lobby to check themselves into a hotel:

  • As a guest I want to be able to check myself in when I have a reservation so that I am allocated a room and my arrival is confirmed

But a more subtle aspect of the role is that it also identifies who requested the feature. In the case of the self check in kiosk, it is the Hotel Management that request the self check in feature.

User stories are reminders to have a conversation in order to elaborate on the detail detail of the feature. Obviously it's important to have the conversation with the right person. In the case of the self check in kiosk, a conversation with a hotel Guest may be useful in order to understand their preferences, but at the end of the day it is the Hotel Management who will provide the details of how the feature should work.

The standard user story template only provides for a single role but a small addition to the template allows both roles to be described:

As a {the requester of the feature} I want the {user of the feature} to be able to {feature} so that {reason or benefit}

The self check in user story can be reworded:
  • As a hotel manager I want a guest to be able to check themselves when they have a reservation so that they are allocated a room and their arrival is confirmed

Use Cases
Use cases have been around longer than user stories. They were first described in late 1980s and in common with user stories, various people have expanded and clarified the approach. The meaning of a use case is formally defined in the UML Standard:

Use Cases are a means to capture the requirements of systems, i.e., what systems are supposed to do.

Use case diagrams are a visual approach for describing software features. Unfortunately, use cases shown on use case diagrams are often confused with narrative-based use case scenarios that describe the detail of a use case. The confusion arises because both techniques are often referred to as simply 'use cases'.

The features described with user stories can also be described using a use case diagram:


Although often forgotten, the bounding box is an essential element of the diagram that defines the subject of the use case diagram. The can be a software application, component or a 'theme' used to group related features. In this case the subject is a Hotel Management System (HMS).

The ellipses inside the bounding box represent the features (or use cases) implemented by the HMS.

The stick figures connected to the features, represent users (or actors) that use the features of the HMS .

External systems and devices that use features can also be included on the diagram but they should be represented with rectangles to avoid confusing them with human users. External systems and devices can also be secondary actors that provide services that are used by the HMS.

A new feature illustrates the use of secondary actors:
  • Notify change to accommodation reservation

Enter new accommodation reservation and Amend existing accommodation reservation both use this feature to notify a guest of a new or changed reservation. The SMS Gateway is a secondary actor that is used by the HMS to send notifications to the guest.

Over time, use case diagrams have been refined by adding new elements in an attempt to incorporate some aspects of use case scenarios. This coupled with the fact that large diagrams can quickly become overly complicated, has meant that use cases have fallen out of favour in recent times, which is a pity as they remain one of the only ways to describe features visually.

In essence, use case diagrams are based on two simple natural langue templates:

The {user or external system} uses the {subject} to {feature}

The {external system} is used by the {subject} to {feature}

Using these templates, the use cases shown on the diagram can also be described using natural language:
  • The call centre operator uses the HMS to enter new accommodation reservation
  • The call centre operator uses the HMS to manually cancel duplicate accommodation reservation
  • The call centre operator uses the HMS to amend existing accommodation reservation
  • The front desk clerk uses the HMS to amend existing accommodation reservation
  • The front desk clerk uses the HMS to periodically list overseas guests that checked in last week
  • The SMS gateway is used by the HMS to notify change to accommodation reservation

Notice that without a reason or benefit, the feature Periodically list overseas guests that checked in last week has not been identified as an unnecessary feature.

Also notice that two features from the original list have not been included:
  • Automatically cancel accommodation reservation if the guest is a no-show
  • Automatically add provisional accommodation charge at 2am each day

This is because they are internal system features and don't interact with an external user or system. Use case diagrams are not intended to describe internal system features. However, this seems to bother some people who try to devise ways to include internal features on use case diagrams.

A popular approach is to represent the subject or time as external systems.


The flaw in this approach becomes obvious when the features are described in natural langauge:
  • The HMS uses the HMS to automatically cancel accommodation reservation if the guest is a no-show
  • Time uses the HMS to automatically add provisional accommodation charge at 2am each day

Formal Requirements Statements
Software engineers and business analysts have been describing software features using formal requirements statements since the 1960s. As others have pointed out, there are many problems with this approach. Perhaps the greatest problem is the sheer effort required to stay awake when reading lengthy formal requirements documents.

Unfortunately, there are times when this approach is necessary and so it is worth understanding.

A feature described using the verb-noun template can be converted into a formal requirements statement by adding a 'subject' and an 'obligation' to the basic verb-noun template:

{subject} {obligation} {feature}.

using the template, features can be described using formal requirements statements:
  • The HMS must provide the ability to enter a new accommodation reservation
  • The HMS should provide the ability to amend an existing accommodation reservation
  • The HMS could provide the ability to manually cancel a duplicate accommodation reservation
  • The HMS must automatically cancel an accommodation reservation if the guest is a no-show
  • The HMS must automatically add a provisional accommodation charge at 2am each day
  • The HMS won't provide the ability to periodically list overseas guests that checked in last week

In these examples, obligation has been described using the popular MoSCoW prioritisation technique:
  • Must Have - this feature is essential, key stakeholder needs will not be satisfied if this feature is not implemented
  • Should Have - this is an important feature but if it is not implemented at this time, there is an acceptable workaround until it can be implemented at a later date
  • Could Have - this is a 'nice to have' feature that may be possible to implement at this time but it will not be implemented if there is insufficent time
  • Won't Have - the full name of this category is 'Would like to have but Won’t Have at this time', features in this category will not be implemented within the the current planning horizon

Comparing Approaches
So given that there is no standard approach for describing software features, which approach is the best to use? As mentioned before, each approach has its own advantages and disadvantages:


As the comparison shows none of the approaches capture the full set of information that can be used to describe a feature. Of course, it is always possible to extend an approaches to include the missing information.

For example, user stories could be extended to describe features used by external systems:
  • As an HMS I want to be able to use the SMS gateway to notify guests of changes to reservations

But as we have seen with use case diagrams, ad-hoc extensions can result in an approach that tries to be 'all things to all people' and in many cases is actually based on flawed thinking.

Feature List
The concept of using a list to describe features (called a product backlog) has been popularised by SCRUM. Many people believe that the features in product backlog should always be described with user stories. In fact, SCRUM doesn't define a specific approach to be be used for describing features.

If features are described in a list, it is easy to add additional information to the description by adding columns to the list.

The feature list below illustrates how the full set of information from user stories, use case and formal requirements statements can be added to the features list:


Capturing features as a list makes it easy to filter and sort the list in different ways.

If required, user stories, use cases and formal requirements statement can easily be produced by substituting values from the list into an appropriate place in the user story, use case or formal requirements template.

Compared to other approaches, the feature list can be extended in a consistent way by adding additional columns.

For example, columns could be added for:
  • Story points or other estimates of effort
  • Any assumptions on which the feature description is based
  • Any risks associated with the feature
  • The planned release date of the feature
  • A cross reference to business worlkflows
  • The subject matter expert for the feature
  • ...