The Feature Funnel: More On Ambiguity (aka Describing Software Features)

I ended my post on qualifying the wishlist by promoting the benefits of a glossary of terms. This post will continue to explore the problems of ambiguity associated with natural language.

In addition to establishing a glossary, another way of ensuring consistency across features, is to employ a standard template for describing features. I have long promoted goal-oriented descriptions for features and base my feature descriptions 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 must be perform to achieve a goal.

• Enter reservation
• Amend reservation
• Cancel reservation
• Add accommodation charge
• List guests

Naturally all the nouns used in feature descriptions 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 conditions that trigger or constrain the feature.

• 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 descriptions of features.

• 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 easily. Just add the user of the feature and the benefit provided by the feature.  This is often 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 as 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!!!)

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 a test case.

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:

• 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 a noun form and moving it to the end of the feature description.

• Accommodation reservation management
• Guest stay management
• Food and beverage management
• Housekeeping management

This concludes the discussion of ambiguity for now. Next up is the question “Is there an alternative to the feature that will achieve the same goal?”.