Describing Software Features

Posted on March 20th, 2015

The Requirements Discovery Canvas is a visual tool that helps teams discover and organise software requirements. Inspired by the Business Model Canvas, it provides a framework for collaboration, that can be used by both agile and traditional software development teams.

In my last post I discussed how to prevent a list of features degenerating into an unruly wishlist of disparate features.

In this post, I am going to focus once again on the "Features" column of the canvas which prompts a team to answer the question, "How could the stakeholders use software as a tool?". The other columns of the canvas provide the context for answering this question with the canvas as a whole providing a visual framework for organising what the team discovers.

For agile teams the "Features" column represents a product backlog, which drives release planning and incremental delivery of the solution. For traditional teams, the "Features" column represents the initial scope of the solution that will be later elaborated into detailed requirements.

Describing Features

Descriptions of software features can be based on a simple verb-noun template.

The verb part of the template either describes:

some action that can be performed by a user of the product; or

some internal function of the product.

The noun part of the template describes the object (or target) of the action. Together, the verb and noun describe some action that the user performs to achieve a goal.

Enter reservation

Amend reservation

Cancel reservation

Add accommodation charge

List guests

Any nouns included in a feature description should be defined in a glossary.

Accommodation: A temporary place to stay. May be provided by a room, suite, chalet or dormitory.

Guest: A person who occupies accommodation at a hotel.

Reservation: The arrangement by which accommodation is secured in advance of a stay.

Qualifying Features

The purpose of a feature can be made clearer by qualify the noun in the feature descriptions. One way to do this is by adding additional nouns (or noun phrases) that clarify the object of the verb. These additional nouns may be drawn from existing glossary definitions or, depending on how frequently they are used, they may require their own glossary entries.

Enter accommodation reservation (so the reservation is not confused with a restaurant or spa reservation)

Add accommodation charge to guest’s account (so the account is not confused with a supplier's account)

List dormitory guests (so that the guests are not confused with guests staying in more salubrious accommodation)

Traditionally, nouns are qualified with adjectives (or adjective phrases) so it is quite natural to add adjectives to feature descriptions.

Enter new reservation

Amend existing reservation

Cancel duplicate reservation

Add provisional accommodation charge

List overseas guests

In a similar manner, verbs can be qualified with adverbs (or adverb phrases).

Manually cancel reservation

Automatically add accommodation charge

Periodically list guests

If required, features can be further qualified by adding constraints.

Cancel reservation if the guest is a no-show

Add accommodation charge at 2am each day

List guests that checked in last week

Basing feature descriptions on the verb-noun template, combined with careful qualification of verbs and nouns, can remove a lot of ambiguity from feature descriptions.

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

User Stories

Applying the verb-noun templates is a great way to initially identify features but agile teams often want to describe features as user stories. Converting a feature described using the verb-noun template into a user story is quite straightforward. Simply add the user of the feature and the benefit provided by the feature.

These additional components are summarised in the standard user story template.

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

The features we have used in examples 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 reservation feature is used by both the Call Centre Operator and the Front Desk Clerk but for different reasons. Also notice how the benefits justify the feature and link the features to business needs (except of course in the case of the last feature).

Outcomes and Benefits

Often identifying the reason or benefit that justifies a feature is the most difficult part of writing a user story. Once again the verb-noun template can help. Changing the verb to past tense and reversing the order of the verb and noun reveals the intended outcome that is associated with the feature.

New accommodation reservation entered

Existing accommodation reservation amended

Duplicate accommodation reservation manually cancelled

Accommodation reservation for no-show guest manually cancelled

Provisional accommodation charge automatically added at 2am each day

Overseas guests that checked in last week periodically listed

Viewing features as outcomes often helps to identify the benefit or reason for the feature. It can also help with defining acceptance tests by describing the expected outcome of the test.

Capabilities

When a group of related features are features are grouped according to a theme, it is often useful to use the verb "manage" to describe the theme.

For example:

Manage accommodation reservations

Enter new accommodation reservation

Amend existing accommodation reservation

Manually cancel duplicate accommodation reservation

Automatically cancel accommodation reservation if the guest is a no-show

Alternatively the group of features could be describes as a "capability" by changing the verb into its noun form and moving it to the end of the feature description.