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.
About the author
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.