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!




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


What has system architecture got to do with requirements? This was the first question in this series written by Hillary Sillitto. We have since then read about how an architecture may be used to address requirements coherence and completeness. Its now time to move on to the next step in Hillary’s six step approach to system architecting.

Going from black box to glass box

Now we get to what most people think of as the main point of system architecture, the logical and physical “glass box” views of the system. These are steps 4 and 5 in our six step process.


It’s very tempting to jump straight into the physical solution, because we usually have preconceived notions about how the system should be constructed. But if we do that, we’ll probably just do it the same way we always did. Often there is a cheaper, or better, or smaller, or more reliable way of doing part of the system; or the part you intended to use is no longer available; or the supplier put the price up and you need to look at alternatives. If any of these happens, and we didn’t do the architecture properly, we’ll find we can’t separate out the requirements for the bit we’re replacing, so we have to do the complete requirements allocation again from scratch.

That’s why we do the internal architecture from two quite distinct viewpoints: the logical perspective, where we think of the system as a network of interacting processes or sub-functions; and the physical perspective, where we think of the system as a set of interconnected parts.

We break each system function down into a set of sub-functions or internal processes. The sub-functions are broken down or “decomposed” just enough to allocate them to a conceptually feasible “design element” – which could be a bit of hardware, or software, or a process, or operator task. The sub-functions and the flows between them form a “process thread” running through the system from input to output – like the mission threads we developed in Step 2, but this time inside the black box. The requirements for the function are then decomposed so they can be allocated to the sub-functions.

Then we choose appropriate specific solutions for implementing each sub-function, and work out the best way to group these design elements into an efficient set of “physical” parts. (In this context, the “physical” architecture includes software and processes and people and organisations, not just hardware.) The requirements for a part are just the requirements for the sub-functions allocated to it, and a share of the physical budgets for space, weight, power, etc. You can think of this as “allocating bundles of functionality, with the accompanying bundle of requirements” to the physical part.


To summarise: the logical architecture provides a framework for flowing down the functional, behavioural and performance requirements; the physical architecture provides a framework for flowing down the physical attributes and characteristics; and the allocation of logical to physical components completes the flowdown of requirements from one level in the system hierarchy to the next.

When we’ve completed this step in the architecture, each part will have its own set of black-box requirements – functions, performance, behaviour, states and modes, and physical characteristics.

This all sounds a bit over-analysed. But the payoff comes when we have to change something. Suppose we get some whizzy new technology that lets us consolidate two parts into one, or we need to change the logical-to-physical mapping to satisfy some speciality engineering constraint. We need to do a lot of work to re-specify the parts if we don’t have the logic for what each part does and why. But if we have already done a decent job of the logical architecture, we don’t have to re-engineer the requirements from scratch; we just allocate the relevant sub-functions to a new set of physical parts, and the requirements go with them. We can make precisely-targeted changes to parts of the system without having to rethink the whole system.

Previous post in this series on Architecture

This post is part of a series on architecure 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

Next post in this series

Next post will be the last of this series by Hillary Sillito. Then he will discuss decisions, trade-offs and architectural requirements. I can´t wait!

See you then!


People don´t understand or listen properly to me. Should I be mad?

My Webex extravaganza…

Last week I had the opportunity to host a Webex with the provocative title “Start over and do it right! The art of writing high quality requirements”.

It went super and the audience listen to me talking about human behavior, the art to write a statement in natural language that is clear, correct, complete and consistent within its context. I did not ONCE talk about how you go about and develop the System solution, but I did the “mistake” of showing that your goal is to go from A (a user need) to B (a System that fulfills A) with a time lime between. So, I got feedback stating:

“This is waterfall and that’s not very Lean. I expected to hear something new”.

Or what I think is the best comment of them all:

“The presenter stated that you shall write the requirement in the beginning and that’s not Agile. 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. We focus on the customer instead”.


For me the above feedback given to me shows that:

  1. People are still in the Waterfall vs. Agile development war. Why? If you use a waterfall model correctly, plan your tasks and iterate accordingly, this can be both Lean and Agile. Why have we not come further? I have heard this debate for 20 years now and it’s not taking us anywhere. Give it a rest!
  2. I did a mistake to present a straight time line (with an arrow I might add) from A to B and instantly people thought that I meant that you do thing once and you never go back, EVER? I did not once said that, so Why is the interpreted like that?

The art and science of  NPL

But again, it just proves me right in the first place.. I talked in my WebEx on human behavior and how our brain interprets information (written or spoken). There is a fascinating field of Neuro linguistic programming (NLP) that encompasses the three most influential components involved in producing human experience: neurology, language and programming. The neurological system regulates how our bodies function, language determines how we interface and communicate with other people and our programming determines the kinds of models of the world we create.


So, what happened in the WebEx? Since the body language where minimized to just showing my face, the spoken information was a one way street with no interaction with the auidience, the listeners “programming” caused problems. Even if I NEVER said the things mentioned in the feedback, the listeners clearly THOUGHT that was what I was trying to say. One of the most prominent flaws we humans have is to first fit new information into our existing (old) belief system to verify that we are still correct.

The fun thing is really that this was EXACTLY my point in the Webex! We need to be better at stating requirements in the first place (and itterate of cause) so that the reader  don’t end up having to interpret, misunderstand or read between the lines. We need requirements that are CORRECT, COMPLETE (as a set of requirements) and CONSISTENT within its environment/context.

But, I shouldn´t be that angry or hurt. The problem is still mine if I go back to the WebEx in this case. I cannot blame the audience for not understanding me. They were both as intelligent and experiences as me (ok, almost.). BUT I did not reach them with my ideas or intentions. I was not clear enough with my information and did not adopt it to audience!

And by the way. It does not matter if you write requirements in natural language or write use-cases, personas, scenarios, diagrams, drawings, SysML-models, SCRUM back logs, test cases (or even WebEx feedback to a grumpy old fart)….. The problem may occur regardless the PACKAGING of the information!

Stay tuned and for god sake. Give me some feedback!


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


What has system architecture got to do with requirements? This was the first question in this series written by Hillary Sillitto. This time he will discuss how the architecture itself can help in the difficult task of knowing when you have a complete set of requirements.

How to know when you are “sufficiently complete”?

In the last post, we talked about using Steps 1 and 2 of the six-step systems architecting process to understand “what the requirements should be”. To make sure the set of requirements is coherent and “sufficiently complete”, we need to work between steps 2 and 3, the Operational and System perspectives, until everything ties up.


To complete Step 2, we weave all those mission threads together into a tapestry that we can think of as “a day in the life of the system”. This describes all the things that might happen in a typical, or not-so-typical, day of the system’s operation. Things sometimes go wrong, and the user experience is radically influenced by how the system copes with these “rainy day scenarios”.

We look for “simplicity through the complexity”, for common repeating patterns in the mission threads, so that we don’t generate new requirements for each mission thread, but find a common set of requirements that allows all relevant mission threads to be satisfied. We’ve probably finished the operational architecture when we can add more relevant mission threads and don’t find any more requirements.

In Step 3, the system perspective, we view the system as a “black box”.  The first thing we need to do in the system perspective is to choose where to put the “responsibility boundary” of the system. Where to put this “outside surface of the black box” is guided by how easy it is to define the interfaces. The architecting heuristic (rule of thumb) of “high internal cohesion, low external coupling” is a good one to apply.

OpenSystemRepresentation.svg(source Wikipedia)

Depending on how we chose the system boundary, we might need to specify the system as a product (e.g. a cash machine), or as a service (e.g. the service of providing cash), or in terms of the capability it provides (e.g. the ability to offer a range of secure and dependable banking services). Depending on this choice, we’ll need to write the requirements differently.

We should specify the requirements for the system in a way that can be tested at the boundary and doesn’t make any assumptions about its internal design (remember, it’s a “black box”), so that we don’t pre-empt design choices and unintentionally exclude solution options. We need to think about how the system will satisfy all the use cases contained in the mission threads. We need to define the functions of the system, how well they need to be done (performance), under what operational conditions, and in response to what inputs (behaviour).

The external system interactions we identified from the mission threads in Step 2 need to be supported by appropriate interfaces. What throughput (flows of material, energy and information) do these interfaces need to support, in what operational conditions? If any interfaces are asked for that don’t seem to be involved in any of the mission threads, have we missed an important mission thread? Or is the interface not needed?

The concurrency we looked at in the operational perspective helps us choose the states and modes for the system. States and modes provide a good framework for organising the requirements, and for identifying those which need to be met all the time, and those which only need to be met in some modes, configurations or situations.

And then we need to specify the physical requirements for the system to be usable in the intended operational environment. A requirement for the new British aircraft carriers was to be able to pass under the Forth Bridges, while Portsmouth Dockyard needed to be modified to accommodate them.

Previous post in this series on Architecture

This post is part of a series on architecure 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

Next post in this series

Next post will continue to discover the relations between architecture and requirements and focus on the rational and allocation of requirements.

See you then!