Why Your Written Requirement Is Not Your Scope
This should be a bit obvious by now, especially if you have followed any of the other stuff I have written. Information that is written down gives us a false sense of assurance that we have successfully “captured” the requirements. Everyone sits at ease and kicks back, waiting for development to begin. But sometimes and in fact, oftentimes, it leads to mayhem before it leads to any productive development.
In order to demonstrate this nugget of advice that we have seen espoused in countless Agile practice books (for instance- https://www.mountaingoatsoftware.com/books/user-stories-applied) , I will share an example of an actual “written understanding” gone wrong that I saw.
Please take a good look at the picture below.
This was a notice that was put up at a diagnostic clinic that a friend and I visited. If you read the second line, it says,
“Kindly expect minimum scanning + waiting time of 1 hour”
Does the above mean that the patient should expect minimal scanning to take place and a waiting time of 1 hour? Or does it mean that the combined time for scanning and waiting is 1 hour? It might seem obvious to some of us, who know that these echo scans can take time and they are not minimal in any shape or form. But without that context, the true intent of that statement can be perplexing.
Let’s extend that to another example, again something I have seen in a user story before.
Acceptance test # The user must be able to preview the PDF and download it in less than a minute
You probably already know where I am going with this. It would still seem fairly obvious that the 1 minute limit applies to the download and not the preview.
But let’s take this,
The user must be able to access the repository and open a document within a minute.
How would we interpret this as? Without the context of the project, either interpretation of the statement is valid.
I have been sharing quite a few examples of this and-grouping kind. These can actually be solved by splitting them into two lines,
- The user must be able to access the repository
- The user must be able to open the document within 1 minute etc. (it won’t work always though)
But written requirements can get our heads in a warp in other ways as well.
Consider this simple statement,
The user should be able to sort the application IDs in ascending order.
While this may seem very trivial, but what exactly is ascending order, especially, if we allow alphanumeric characters?
Does ‘a’ come before ‘A’ or after it? i.e. a sorted list would be either
Aa13451
aa13451
OR
aa13451
Aa13451
Similarly, Does ‘a’ come after ‘0’ or before it? (some would say ASCII based sorting would make this fairly straightforward, but then, it is a detail that is missing in the spec and it needs to be discussed!)
It is these sort of questions that get clarified with discussing the requirement. During discussions, any written assumption may get challenged and changed and even new specs may emerge.
Another examples is ‘search’. Functionality is notorious for being difficult to cover in a written spec. Do we allow auto-complete?
Do we sort the search results in any way?
Do we let the users see suggestions?
Do we cache searches? If we cache searches, then how much of it do we cache?
It is for functionality like search and many others, where user stories’ ‘N’ in the ‘INVEST’ (https://www.agilealliance.org/glossary/invest/) comes to the rescue. Since user stories are not a contract (at least not supposed to be :) ), there is always room to discover and detail it later and deliver it.
Without discussion and written requirements being your only scope, written requirements (and poor analysts and devs) have nothing left to fend for themselves. With discussions, they are an empowered bunch who can truly shape your requirements to the product you always needed to build.
