Lonsdale Systems
Courses Resources Blog Portfolio About Contact Search Feed

More About Describing Software Features

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:

or maybe as a use case: 

or possibly with a diagram:

or even as a formal requirements statement:

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:

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:

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:

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:

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:

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:

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:

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:

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:

In these examples, obligation has been described using the popular MoSCoW prioritisation technique:

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:

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:

More About Describing Software Features
Courses Resources Blog Portfolio About Contact Search Feed
Lonsdale Systems