5 Language Tips to Get Rid of Ambiguity in your Requirements

In this post, I’m going to show you how to create clearer requirements, avoiding common language habits that can introduce ambiguity.

Problem

Ambiguous and incomplete requirements can lead to project delays, rework and budget overruns.

We have ambiguous requirements when:

  • A single reader can interpret a requirement in more than one way and is unsure which the intended interpretation is
  • Several readers can interpret a requirement differently from one another

So often, requirements are ambiguous to their readers, despite the writer’s best efforts.

Incorporating the following simple language habits into requirements writing will help eliminate ambiguity and ensure consistency.

question_s

Tip 1: Use Active Voice

Passive voice is usually weaker writing since it makes it unclear who or what is doing the action.

Do not assume your reader knows who the actor is. Specifying an actor results in greater sentence clarity.

For example, use the active sentence

The system will generate the report.”

instead of the passive sentence

The report will be generated.”

active_voice_s

Tip 2: Avoid Dangling Participles

A participle phrase is a phrase that acts as an adjective. Sometimes, the noun that the participle phrase is intended to modify is not stated in the sentence. In this case, we talk about dangling participle, and it is something to avoid for the sake of clarity.

For example, consider the following sentence:

“After attempting to generate for more than two minutes, the customer will have the option to cancel the report.”

Here the missing word is the system because the system is attempting to generate the report.

This requirement is ambiguous because it sounds as though the customer is attempting to generate the report for two minutes when the writer’s intent is to focus on the length of time it takes the report to generate.

Correcting the dangling participle makes the requirement clearer:

“After attempting to generate for more than two minutes, the system will offer the customer the option to cancel the report.”

dangling_s

Tip 3: Use Specific Nouns

Use specific nouns to clarify who is performing an action.

For example:

The user will be able to export a report once a month.”

The noun user is too generic, maybe we are talking about a customer or vendor.

The following version of the same requirement is much better:

The vendor will be able to export a report once a month.”

nouns_shade

Tip 4: Clarify Pronouns

Repeatedly using specific nouns like “system” or “vendor” instead of pronouns may seem a little bit cumbersome, but will improve clarity.

For example, the following requirement is ambiguous because it is not clear which noun the pronoun it is referring to:

“The system will generate the report, and the UI will display the results. It must be redesigned to accommodate the report.”

What must be redesign, the system or the UI?

The next example is clearer because we simply repeat the noun again for the sake of clarity:

“The system will generate the report, and the UI will display the results. The UI must be redesigned to accommodate the report.”

pronouns_shade

Tip 5: Avoid Would and Should

Using the words would or should literally means that something is optional, but generally, that is not what the writer means when talking about requirements.

So, to avoid confusion, the best option is to use stronger words like “will” and “must”.

For example, consider using the following sentence

“The system will import all data.”

instead of

“The system should import all data.”

should2

Conclusion

Integrating these language habits in your requirements to decrease ambiguity, will give you several benefits, saving you time in your work. Team members will ask for fewer requirements clarifications and the project cycle will be faster!

References

 

 

Advertisement

The 4 Reasons Why User Stories are Better than Requirements Specifications

In this post I’m going to show you why User Stories are a better solution than Requirements Specifications to effectively understand user needs and build successful products.

Introduction

Software requirements is a communication problem.

How do you decide what a software system is supposed to do?
How do you communicate that decision between the various people affected?

communication_problem

Experience has taught us that Requirements Specifications do not work anymore in today’s  world and that User Stories are a much better solution.

I’m going to explain you why in this post…

What are Requirements Specifications?

A typical Requirements Specifications fragment is the following:

IEEEFormat

There is a tremendous appeal to the idea that we can think about a system and then write all the requirements upfront.

Requirements Specifications written like that have sent many projects astray because they focus attention on a checklist of requirements rather than user goals.

What Is a User Story?

A user story describes functionality that will be valuable to either a user (who uses the system) or customer (who pays for the system).

user_story

The format of a User Story is the following

As a <Role> I want <Function> so that <Benefit>

as in the example below

As an executive, I want to generate a report so that I can understand which departments need to improve their productivity

Our goal with user stories is to write down a short place holding sentence that will remind developers and customers to hold future conversations.

Why User Stories are better?

1. Comprehension

A way that extensive upfront Requirements Specifications can kill a project is through the inaccuracies of written language.

The shift toward verbal communication of User Stories provides rapid feedback cycles, which leads to greater understanding.

2. Planning

A difference between User Stories and Requirements Specifications is that with the latter the cost of each requirement is not made visible until all the requirements are written down.

With stories, an estimate is associated with each one right up front so that they may be conveniently used for release planning.

3. Resiliency

Change always happens in projects…

  • Users and customers do not generally know exactly what they want
  • Many of the details needed to develop the software become clear only as the system is being developed
  • Product and project changes occur
  • People make mistakes

User Stories embrace change because

  • Do not need to be all written before developers can begin coding the first
  • Encourage deferring details because we can write them at whatever level of detail is appropriate in a given moment.

4. Prioritization

It’s hard to prioritize and work with thousands of sentences all starting with “The system shall…”.
That difficulty usually results in having the user considering 95% of the requirements high priority!

On the opposite, User Stories can be easily ordered by priority.

References

Mike Cohn