NLP · requirements · Uncategorized

Fifty shades of requirements, part one – The spiral of death

The misplaced and flawed conception of requirements work leads to a death spiral


Lindsay Weinstein and Jacob Simon perform a so called death spiral at the 2015 U.S. National Figure Skating Championships.

Imagine that you are working in an organisation with diverse knowledge of requirements work. Some projects work better than others and you don’t think so much about it. You write requirements because you are used to do so and to be honest, you don’t really understand why. When you started to work here you tried to question the current way of working but had no clear answer from either colleagues or your manager “we use requirements as part of contracting” you were told. You have some processes in place explaining the different steps on a high level focusing on handover, roles and responsibilities. You also have a requirements management tool where you store your requirements. You basically use this to be able to link requirements to test cases in the testing tool and that seems to work.

So, now after a couple of years on the job you have stopped to think about the steps of writing a specification at the start of any new project. You have actually seen that even though you discuss about the increased technological complexity in your domain, your feeling is that you cut-n-paste more now than ever and you look with envy on that other project that talks about new agile methods and reduced amount of documentation. To be honest it’s not at all fun writing documents. That was not the reason why you chosen to become an engineer in the first place.


“I wonder if we should consider skipping the boring requirements definition part and go straight to the more interesting and (for me) rewarding design phase”, you think. No one seems to care anyhow, well that’s not entirely true. Both people from contracting and test usually come when we are almost done and starts to question our work, saying that we have deviated from the requirements. It’s a habit they evolved actually. The new project that works agile explains that they will not have this problem. They have daily meetings and meet the customer on a regular basis. That’s good since the customer have changed their mind a few times now, even after the contract was signed.

You have also noticed when you get those monthly reports that the company is starting have problems with lost market shares, lower cash flow due to projects having problems delivering and increased customer complaints. But these problems will surely fix themselves now when the CEO was replaced and the new one talks about “maximizing the value flow” and put focus on “optimizing the innovation throughput”. You have also heard rumours about a reorganisation to help the organisation to change.

Does any of this seem familiar in any way? Well, for me I have come across this multiple time in the past. I have reorganised just to be reorganised six month later. Introduced new improved processes and Lean methods and coached, trained, managed and supervised people with various degree of interest or change resistance.

I will try to elaborate around WHY the above occur and especially the role that BAD REQUIREMENT PRACICES. So what has requirements got to do with all of the above? I call it the Spiral of Death.

The spiral of project deathThe spiral of death

So what is this picture basically saying? Well, If one starts with unclear needs from a customer or other stakeholders, they will for sure result in an unclear input to the project and design efforts. I am not saying in any way that we need to stay in the needs definition or requirements specification phase “for ever”, but we absolutely need to be sure of the boundaries of the project (the scope), the market drivers (the unique selling points), the risks and the fundamental needs from bench marks, surveys and support and failure logs.

If we rush through this phase and quickly “cut and paste” from previous and similar projects we will start of on the wrong foot, loose track on special needs, the context and engineering decisions made in the source project. We will start the troublesome journey downwards the spiral of death.

But, you might say. We do extensive peer-reviews on our requirements both before we start as part of the contract review AND as part of our engineering process OR we do agile development so we find out quite early where we have made mistakes and are able to correct these. The problem must lie somewhere else?!

NO, they absolutely do not and next time I will continue to discuss this topic focusing on understandability, peer-reviews as a phenomenon and provide examples and evidence supporting my statement made in this blog post.

Until then, be careful out there 😊

requirements · stress · Uncategorized

Can you put Requirements on Christmas?

I feel that to many people do, perhaps to many. If I where to put some on Christmas what would it look like? Just from the top of my head it must include so many things:

The Christmas SHALL be full of happiness, joy, family gatherings, presents, good food, etc., etc.…

First, One cannot put that requirement on the <Object> “The Christmas”. It is just a word, but it means so much to people. They put in their own emotions, expectations and dreams into it. Second, as a requirements guy I can say that you MUST avoid piling attributes to it like I did in my example. But we all tend to do that, right? I can really imagine the failed verification on my requirement. I hope you can to. I need to relax and back off for a while.


Before you continue reading this, do me a favour. Put down what you’re holding (in your hand or your head)—your shopping lists, your third cup of coffee, your assignments, the phone call you should be making—and sit quietly for just 60 seconds. If you’re at work, don’t worry what your colleagues might think—this time of year everyone would love to contemplate, and more often.

Hello? Anyone there? It felt good to escape for a minute, didn’t it? But come back—it’s that time of year again: the modern miracle known as THE HOLLIDAYS, when into the dark little month of December, we squeeze in a lot of celebrations, from school gatherings, office parties and of cause family celebrations. Throw into that mix a generous dose of unrealistic expectations, budget-busting shopping, dysfunctional family feasts, airplane flights, darker days, colder weather, excess eating and drinking, and no wonder that along with “peace on earth”, come seasonal stress, exhaustion and depression.

So, lets rephrase my Christmas requirement:

The Christmas SHALL mean love for my fellow man.

By that expression (or requirement) I mean that people should get along with one another, have good feelings toward one another, and be nice to one another. It is this humanistic interpretation of Christmas that is celebrated in so many Christmas movies we either love or hate.


So by this I wish you all a Merry, Merry Christmas whatever you do and where ever you are. I end thios blog post with a warning example captured in a poem by Tess Gurney:

Cars and bustle, rush and hustle,
trolley dashing tempers clashing
Christmas cheer to much beer
mistletoe, plastic snow
christmas holly ‘lets be jolly’
christmas pud, do you think we should?
Turkey, stuffing, granny puffing,
fairy lights, men in tights
pantomimes, palour games
christmas cake, belly ache
as yet another piece you take!
Boxing day, in-laws stay!
Endless repeats on the telly, and again from your belly!
No more hassle…the odd brussel!
christmas farce….
A pain in the arse!


The over-reliance on Requirements Management tools as the engineering Messiah


Since I started to work with requirements (information) quality I’ve met a lot of folks out there that in my opinion have an unhealthy belief in requirements management as the sole facilitator of the requirements work needed.

If I asked: “Do you work with requirements?”, almost immediately the conversation turs into either a discussion on tooling (IT support in the shape of a relational database for tracing different requirement statements to and from each other) OR in a discussion on the need to change over to more Agile ways of working using User Stories, Personas, Modeling, etc. from the old way of working (water fall and written requirements).


If we for a moment stop this here and just thinks about this… I just want to reason with you a bit here..

I asked about If someone works with requirements, right? Not about tools or development processes or methods, right?

What are requirements?

Requirements are capabilities that a product must meet to satisfy a stakeholder’s need to solve a specific problem. The stakeholder’s needs can come from a number of sources including compliance to a standard or to legal regulations, a business need, a technical situation, market need, competition, etc..

So, why the discussion on tooling or Agile methods? My sense here is that A:

  • People don´t know that requirements are really used for, OR B:
  • They don’t understand why they work with them in the first place.

If we consider the definition of the discipline Requirements Engineering (i.e. all things associated with requirements) it’s like this:

Requirements Engineering (RE) refers to the process of defining, documenting and maintaining requirements in the engineering design process.

So when I put these to together (Requirements and process) I end up in basically the notion of being able to understand a need/problem, defining it in a suitable way (notation technique, language and “chunks”) and maintaining this clearness thought the project endeavor put in place to solve this specific need and problem. Ok, basically that’s the boiled down version.

That means to get from point A (the problem) to point B (the solution) I need to do a lot of clever stuff to understand, define, build, prove and deliver B to satisfy A. The way of working (that endless discussion about development methodologies) is of lesser importance here. You still need to validate in some way that you have understood the problem before you start to run, right?

To solve complex things, I need to develop suitable pieces of this puzzle and give these to the people that needs them to help me. For this I typically need clear pieces of information that together with the other pieces builds the complete picture. I need to describe this specific, correct and unambiguous piece of information. This basically becomes a Christmas tree in shape with the original need at the top which is broken down and developed into those well-known requirement types of functions, constraints and capabilities we are used to see. Each broken down requirements are derived to contribute to satisfy its originator one floor up in the hierarchy. For this we need to keep control over the links that becomes one of the results of this activity. How can we otherwise know what will become the consequence of a change?

But is requirements management enough?

So, back to the question on requirements management tool. Is it enough to have a tool for managing those requirements and links?

No, absolutely not! Have your heard the phrase “shit in, shit out”?

To only focus on the management part of requirements engineering one tends to create an over reliance on the management tool to show when a link requires an overview due to a change somewhere. Haven’t you forgot one thing? Requirements are stated by humans for humans and the knowledge captured because of a decision to state a new requirement in the first place MUST be captured in the sentence put down.

A badly formulated requirement is therefore the parent of a lot of new requirements all of them inheriting the bad genes:


Why requirements quality is important

So, to round of this blog post. Requirement Management IS important, I agree to 100%

One need to be able to trace requirements to do impact analysis on suggested changes, do testing in a clever and incremental way and basicaly have an idea when to be done with the project, but…

Wrong information derived and traced into more low-quality information will lead to a disaster. A recent study actually showed that of all failed projects investigated over 40% had come to the conclusion that it was because of bad requirements or beeing unable to understand the true stakeholder need in the first place. If you are lucky you dont fail your project due to bad requirements, perhaps you “only” get alot of late design changes, angry test teams, frustrated project managers, failed finacial goals and unhappy customers.

You better stop saying that you are good at requirements ONLY because you own a RM tool! Without good engineering practices to discover and formulate the correct and consistent requirements and making that specification complete (to describe full need of functions, qualities and cosntraints), you will still have huge problems, RM tool or no RM tool. Shit in is, and will always be, shit out!

PS. The rest that didn´t blame the requirements for their recent project failure, blamed the project manager. Just so you know. The story contines and so will the failed projects…

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:


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


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


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


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.



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).


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:


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 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.


architecture · NLP · requirements · Uncategorized

Agile doesn´t work!?

By starting with the statement “Agile doesn´t work” you really ask for trouble these days. I was attending a conference earlier this week and I meet Agile coaches, Agile Managers, Agile Testers, Agile Requirement Engineers and Agile Evangelists in general. The conference itself was very good and I got the possibility to talk about the requirements role for a successful project. Unfortunately, I needed to leave early so perhaps you might call me an Agile planner?

No, but on the metro back to the office (you know my Agile Schedule) a LinkedIn post by Oleg Vishnepolsky, CTO at DailyMail in UK, caught my attention. It started “Agile does NOT work!”.


He started; “Try telling someone that you are not agile. You might be arrested on the spot. The issue is that the word agile in the eyes of everyone is similar to the word good. Try telling others that you are not good, and they will call for a psychiatrist.”

I continued to read the post with great joy. I think he is spot on!!

Why Agile isn´t a silver bullet

Agile can be defined as “Agile (software) development describes a set of values and principles for software development under which requirements and solutions evolve through the collaborative effort of self-organizing cross-functional teams” (source Wikipedia).



First of all, don’t get we wrong. I don´t like the approach with “analysis paralysis” and so heavy front loading that you never get through the first base of requirements elicitation and definition. Many organizations have historically lacked the ability to say “this is good enough” and moved further in the development chain. If you stop to long the inertia of badly performed Systems Engineering will force the project to continue and start to develop stuff regardless. They have deadlines and a customer to satisfy, AND doing Agile projects makes it easier to skip the boring work of documenting both requirements and design. The team can go right ahead and do the fun stuff..

But is Agile as an opposite the salvation of any badly performing organization with schedule overruns, lost margins, port system quality and unhappy stakeholders?

I would argue not! You have the same people coming to work, but now let’s do the mistakes in an Agile manner instead.

Well, of cause, Agile basic principles are nice and I do like them:

  • You have customer focus (instead of technology focus)
  • You divide the work in suitable chunks, and;
  • You group in teams instead of stove pipes so that you get much better cross pollination of views and ideas. That’s great!

But it is still humans that needs to understand the problem they are there to solve. Perhaps Agile is a way of getting it better, but not getting it right? Could an old Waterfall organization that goes Agile like this approach because it reveals the problems earlier than before? Are they really looking into the root cause of the problems they are facing (which haven’t gone away just because you went Agile).

The common-sense methodology

Mr Vishnepolsky introduces the common-sense methodology and I like that thinking very much. Instead of digging trenches and throwing dirt on anyone not from the right belief, you might like to make a short retrospect and look at yourself before you continue this argument.

I would like to add my small contribution: For god sake, look at the scope and early requirement definition phase and do it with FOCUS and a sence of INFORMATION QUALITY!

Making it right from start so that people understand what you mean

Ok, I might add that you can develop this type of knowledge using an arbitrary methodology, but just for the sake of it say that you write some business or stakeholder requirements to make sure that you understand the problem you are there to solve. After you have agreed with the stakeholders the task at hand (to a reasonable level of detail) you might develop technical requirements using natural language techniques (writing requirements) and/or doing some system modelling to get the system boundary and interfaces in place. You might have read the architecting blog series here by Hillary Sillitto?!

But who do you have in mind when you do this work? You are not doing this because it’s fun or because someone asked you to, you do it to COMMUNICATE with others. The stakeholders need to understand your solution to his/her need AND the next person receiving your information (developers, testers, integrators, etc.) also need to understand what you are proposingIT_DEPENDSSo, please start to do your requirements with some level of curiosity from the team working with them. You really need to understand their role here as drivers of knowledge from one part to the next. They first of all need to be correct and together with their other requirement siblings at the same abstraction level, they need to be complete (to the degree to level risk and avoid costly errors) and also not in conflict with each other so that one says “right” and another “left”.

But primarily, human write requirements for other humans. Perhaps using a second language and communicating through barriers like: culture, development contracts, technology domains and/or business hierarchies.

That’s my contribution to the common-sense discussion. Over and out!

Read the post by Mr Vishnepolsky here:


Part 5 – Decisions, trade-offs and architectural requirements


In previous posts Hillary has discussed Steps 1-5 of the “six step process” and we have now come to the end of the staircase. It has been so interesting to read how the architecture evolve and let’s not waste any more time introducing this chapter. Here is the final chapter from Hillary Sillito on the subject of; “What has system architecture got to do with requirements?”

A shared mental model

I have discussed the different steps in the “six step process” and have described the steps sequentially, but really there’s a lot of iteration and going back and forth. It’s a learning process – we work on each step in turn to increase our understanding of the whole. The first time through, we go as quickly as possible to build a coherent skeleton. Then we’ll flesh it out as needed to support decisions and give everyone a good understanding of the whole system and how their bit fits in.

A very important aspect of architecture is to give the team a “shared mental model”, so that “everyone is making the same system”.


Equally important, the six steps of system architecture show us how the different perspective are linked, and let us do trade-offs across all the perspectives to make the system cheaper, simpler and more effective.

The physical parts need to be chosen so that they fit together and work together. The individual physical parts that best fit together might not work together so well in “rainy day” scenarios. The parts that work together best for the “rainy day” scenarios might be too big, or take too much power. This is where we get the payback for all that work we did on enterprise and operational perspectives. Maybe we can make the system better, or cheaper, or more reliable, or easier to use, or all of these, if we go back up to Step 2 and change the way the system will be used.

The six step architecting process opens up the range of possible choices and lets us trade not just within the technical solution, but between the technical solution and the operational concept. It might be cheaper to change the way people work than to add complexity to the new product – or maybe we don’t even need the new product at all! Requirements can be renegotiated if we can show, through the architecture, how they make the solution expensive and risky.Hillary_part5

But hold on. I said six steps, and we’ve only talked about five. What is step six? That’s the decision perspective. Each of the other five perspectives involves a set of decisions; but since the perspectives are all inter-linked, we need a holistic view of how decisions interact and have consequences across all the perspectives.

The Decision perspective

Decision structures can be complex. One decision drives another, which drives another, which drives others, which drive the first. Or we have a long decision tree with many branches. So that the work can be planned in a good sequence, we need to build a decision map, which shows us how the key decisions relating to the architecture are inter-related, what order they should be taken in, and what supporting analysis and experimentation is needed to inform each decision.

This brings us to architectural requirements. When we architect a system, we combine knowledge from the problem space of what the customer wants, with knowledge from the solution space of how the system needs to be constructed to work, to keep working, and to be no more costly than absolutely necessary. One of the key architecting roles is to make the system-wide design decisions that impose coherence, consistency and efficiency across the system. These might be design principles for safety and security, common interface and data definition standards, overall power and thermal management, consistent layering schema, consistent start-up and recovery strategies, common MMI look and feel, standardised personnel and training policies, whatever is important for the system of interest.

All these decisions are to meet the implicit customer need for an effective system that is fit for purpose; but most won’t be traceable to explicit requirements in any straightforward way. The requirements management process needs to capture the rationale for the system wide design decisions and ensure they are reflected as requirements on the subsystems.

Previous post in this series on Architecture

This post is part of a series on architecture and requirements by Hillary Sillitto. You can read the previous posts or his personal bio here:

Part 1: what-has-system-architecture-to-do-with-requirements?

Part 2: System requirements don’t appear by magic

Part 3: Part 3 – Using System architecture to Decide if the requirements are coherent and sufficiently complete

Part 4: Part 4 – System Architecture Provides the framework and rationale for allocating requirements to parts

About the author

If any of you have the urge to get into contact with Hillary Sillitto he can be reached through his web page:

Next Blog

This was (sorry to say) the last post made by Hillary on this topic. I wish him to come back and write more! Next time I have another great mind who is going to elaborate about the errors and problems with User-Stories…

See you next time!