peer reviews · requirements

Passive voice requirements – A pain in your Buttocks!?

Why ”passive voice” requirements actually can become a night mare?

If you are like me and like clear and precise requirements with as much clear meaning as possible you might try to wash out some bad language in your requirements. Perhaps you review a set of IT system requirements on the highest level and find a requirement written like this:

“All critical errors shall be logged”.

You might continue and think; “That’s a bit vague but I guess that the reader of the requirement understands this, and the requirement is under a specific section of the set named System management, so is should be fine. I need to discuss with the author on what a critical error is, and we need to investigate how to verify that these errors defined as critical get logged”.

But you might also be a nerd like me and immediately say that “no, we must not have any passive voice requirements in our set of requirements, period!”. Its also in violation of the INCOSE guide in writing requirements, i.e. Rule R2 – Use active voice. But the author of the requirement is much likely not aware of that guide or quality rule in the first place..

Ok, fine. But what does this mean and why is this so dangerous to allow passive voice requirements?

Does it really matter if I write a passive voice requirement? I understand it and this should everyone else also do. Besides, it’s a short high level system requirement and we will get back to the verification details later. These details will come when I start to specify the subordinate level of requirements derived from this one or when I prepare a design solution which will take care of the requirement.

INCOSE says in the rule R2 mentioned above that “requirements not stating the subject must be avoided”. Whats that? I have written that “errors shall be logged”. The word Error is my subject, right?

No, its not actually. When looking into the example sentence in more depth its quite clear that it lacks a SUBJECT. The sentence does not explain WHO will actually log the errors that the writer of the requirement see must be logged. Let’s look at this figure:

From this figure its quite easy to understand that the solution for a passive voice requirement can both be a system function of some sort or a service provided by someone outside of the system.

Same applies to ALL types of passive voice requirements:

Lights shall be integrated in the dashboard… OK. Fair enough, but it this a requirement saying that we require someone to integrate the lights or is the purpose something else?

Perhaps the lights are supposed to be hidden (integrated) in the dashboard and the requirement is trying to capture this?!

The ONLY solution if you ever encounter requirements written in passive voice (and you will) is to go back to the author (or the stakeholder with the need) and ask what’s the purpose of the requirement in question. Ask WHY do you want to integrate these lights? Or WHY do you have to log critical errors?

The answer to these questions will help you to rewrite the requirement so it captures the intention and purpose behind its existence. Because if you don’t do this you will live with the impression that everything is fine, and the development is on its way towards a solution that will fulfil your requirement. The problem(s) will emerge with the first prototype or even worse during verification of the system towards the requirement. Then its LATE in the process and you will have to manage the probable delay or the added cost of doing a late design change.

So, PLEASE don’t ever write OR accept requirements written in passive voice. You have no idea what the result will be, and it will for sure at one point in time pop up and bite you in your butt!

One of the solutions can be to use requirement patterns, butt (hehe) more on that another time….

requirements · Uncategorized

Problems with User Stories and how to improve them – part 2

In the last post Simon looked at the problem of expressing a user need using natural language. He will now continue with part two, the sollution.

User Stories using a structured technique

A technique that has proven to be very useful in reducing errors is patterns. One of the simplest way of expressing a user need is in a User Story, the structure of each story is often based on a pattern as follows:

As a … [stakeholder role] …I want to … [perform an action / record some information][With some frequency and/or quality characteristic] … So that … [description of value or benefit is achieved].

For example:

As a library_user, I want to search for books by title, with speed and ease-of-use, so that I can find all books with similar titles.

Effective natural language user stories/requirements generally consist of four basic structural elements [1]:- entities, actions, events, and conditions. These elements can be used or modified by various cases such as the following:

  • Owner. • Actor. • Target. • Constraint.
  • Owned. • Action. • Object. • Trigger.

Using these concepts, we can re-state the user story template like this:

As a        [Actor or Owner – who/what does the action]

I shall    [Action – what happens e.g. store, update, send data]

for;         [Object – what is acted upon]

on the   [Target or Owned – where the output is sent ; recipient or end state]

with       [Performance – frequency and/or quality characteristic]

when    [Trigger – causes of action; data receipt/user interaction]

unless / even if  [Constraint – business rule or limiting factor]

So that [Rationale – description of value or benefit is achieved].

In the example, ‘library_user’ is the actor, ‘search’ is an action, ‘books in the catalogue’ are the object, the ‘computer screen’ is the target, the performance requirements are ’with speed and ease of use’, the ‘provision of the book title’ is the trigger, ‘incompleteness’ is the constraint / qualifier and ‘finding books with similar titles’ is the value achieved. The user story becomes:-

As a library_user I want to search for books in the library catalogue on the computer screen with speed and ease-of-use when I provide a book title even if the book title is incomplete so that I can find all books with similar titles.

The order:

<ACTOR><ACTION><OBJECT><TARGET><PERFORMANCE><TRIGGER><CONSTRAINT><RATIONALE>

is recommended but there are other orders that are popular, for example Use Case descriptions often use the order:

<TRIGGER><ACTOR><ACTION><OBJECT><TARGET> <CONSTRAINT>

I provide a book title and begin a search for books in the library catalogue on the computer screen even if the book title is incomplete.

Benefits with patterns

Lego_Pattern

Many user stories are more complicated than this example and no one single order can suffice but without including these elements the possibility for misunderstanding is significantly increased.

Another benefit of this template is that it enables an estimate of functional size to be made.

Standardized structured user story expression enables comparisons across time, across teams, across projects, and across organisations. Developers, product owners, and their customers thus have a common way of communicating so that end user value can be delivered in an effective way.


[1] “Writing Effective Natural Language Requirements Specifications” by William M. Wilson


Previous post in this series:

Problems with User Stories and how to improve them – part 1

This was the final chapter on this blog on how to improve User Stories by applying patterns to capture all relevant information. Next time we will look further into patterns.

 

requirements · Uncategorized

Problems with User Stories and how to improve them – part 1

Introduction

In a recent Requirements Doctor Blog post, a contributor wrote “We do many short sprints in my project and do not need to spend useless time in the beginning on writing requirements that no one reads anyway”. While I mostly agree with this comment unfortunately it overlooks another, and often much larger, source of waste – and that is the amount of re-work that is done due to incorrect requirements. Again while I embrace the second principle of the Agile Manifesto “Welcome changing requirements, even late in development”, my experience is that the vast majority of change to requirements is a direct result of inconsistency and incompleteness in the original requirements expression.

I have used the word ‘requirement’ so far but for many people this conjures up the idea of ‘shall’ statements, for example “The system shall go fast”, whereas in an evolutionary approach such as Agile Development, User Stories are a more common starting point. Wikipedia provides the following definition of a User Story, “a user story is an informal, natural language description of one or more features of a software system”, and there, in the middle of the definition, is the Achilles Heel of User Stories; they use “natural language”.

This Achilles Heel is shared by many other development methods and so it is not a problem just for the Agile development paradigm, and the problem is brought about by the lack of adherence to the known good practices for requirements, (User Story), expression.

This is not the place to review the extensive literature on the issues of the use of natural language for expressing the needs and wants of users and customers.  Put simply, left to their own devices with no guidance, writers of User Stories consistently fail to express themselves correctly, consistently and completely, (the same is true of writers of requirements).

I shall leave the topic of completeness for a later discussion, but put succinctly, I believe it is not possible to have a complete set of user stories / requirements. What I would like to discuss in these articles is the topics of correctness and consistency of user stories / requirements, and more importantly how we might measure correctness and consistency so that when we change a User Story we can ensure that it has been improved.

Simon1

Correctness

So when is a natural language user story correct? Well it must follow the syntactic and semantic rules of the language it is expressed in. Natural language syntax is basically about word order and punctuation.

The three words ‘book’, ‘library’ and ‘a’ can be ordered in six ways but only three are syntactically correct, “A library book”, “A book library” “Book a library”; three are not syntactically correct “Library a book”, “Library book a” and “book Library a”.

Natural language semantics on the other hand is concerned with meaning, conveyed by the relationship between words. If we look at the three syntactically correct triads: in “A library book” the word ‘book’ refers to an object and ‘library’ describes a type of book; in “A book library” the meanings have swapped, the word ‘book’ is now the descriptor and ‘library’ is the object being described. Finally, “Book a library” changes the meaning of ‘book’ again, now ‘book’ is an action applied to the object ‘library’! (Book can mean make a reservation).

Consistency

So when is a natural language user story consistent? Simply when a word is used in a specific context then it must have a single meaning and no other word can have the same meaning. In our previous examples the work ‘book’ is used as a descriptor, as an object and as an action. In each of the triads the meaning of ‘book ’can be inferred by its position relative to the other words; the word ‘book’ is in three different contexts but only one can be correct, two must be inconsistent. Now consider this user story, ‘Book the book from the book library!’ Although this is syntactically and semantically correct I would postulate that this user story has a high potential for being misunderstood due to the inconsistent use of the word ‘book’.

So applying correctness and consistency rules to ‘Book the book from the book library’ I would suggest ‘Reserve the book from the library’ as an alternative that decreases the likelihood of wasteful work.

The final issue is how we might measure correctness and consistency. This is relatively simple, whenever a word or phrase breaks a syntactic or semantic rule then add one to the error count and whenever a word of phrase is used inconsistently then add one to the error count. Here are the scores for the various examples:

Simon_2

Spelling and grammar checkers can be used for syntactical checking, semantic checking is a little trickier but automated checkers do exist.

Next post in this series

In the next part of this discussion I will look at how patterns can help us get it right first time.

Happy reading!

About the author

simon.small
Simon Wright, Bsc. PhD

Simon’s experience has been gained in blue-chip companies, and public sector bodies, throughout the world and has a proven track record of helping organisations with their requirement documentation including stakeholder analysis, concepts of operation, requirements development, requirements management and architecture design. Recent clients include: The Russian Atomic Energy Authority – Moscow, The European Spallation Source – Lund, Novo Nordisk – Denmark and the Norwegian Army – Oslo. Simon truly appreciates the separate but related roles of tools, process and people when developing requirement documents. He understands that producing quality deliverables is dependent upon encouraging and sustaining a culture of engagement and commitment.