Spec By Example as an example of one requirement

Hello! I continue the topic of posts about the approach to collecting requirements called Spec By Example. I already did a webinar about the general values ​​of this approach (about it a little later), and today I want to show how it works on the example of a fairly simple, at first glance, requirement. The requirement itself sounds very simple:

The system should display the level of fullness of the warehouse by displaying the number of goods of each type. When shipping / receiving goods, the value must be updated.

In principle, nothing complicated, but let's see what surprises lurk inside!

Let's go in order, as the methodology suggests. And you should start with

Definitions

If there is no common understanding of terminology, then perhaps this is a sign that the parties concerned have not really agreed on other things? These may be business goals, business processes, or functions that the system requires. A simple check of terminology can reveal serious shortcomings in the understanding of the project.

Therefore, we must start with what we consider our dictionary and where the definitions come from. It can be ordinary dictionaries, any books, corporate standards and so on. Ask yourself, do you understand the meaning of nouns and verbs? Be sure to remember where you get this definition. Pay attention if it does not cause any contradictions with what you already know.
And most importantly - ask your customer to check with you that all this is true.

Regarding our case, it will be useful to find out:

• what will be stored at all in the warehouse?
• Are there special goods areas, such as a refrigerator?
• How is the shipment / reception process?

Functionality

When we talk about requirements, we need to think about features and visualize them, and not abstract UML in a vacuum. And visualization allows us to understand this much more clearly, because each process is displayed through its steps and each step and becomes a feature. Due to this, the reception of Story Mapping gives such a cool result.
So, when you read the requirements, pay attention to the following things, which are independent features:

• Named features - users and analysts may already have decided what features they would like to see in the system. Examples include Order Entry, Search Screen, Status Report.
• Phrases like: "The system will {verb} {object} '. Typical verbs: add, update, delete, process and so on. An object can be any entity or process in a system, for example, a customer, order, product, person, invoice, and so on.

For our case, the following features are clearly distinguished:

• shipment of goods from stock
• goods reception at the warehouse
• registration of goods in stock

Results (Outcomes)

More than anything else, requirements should describe the results of the work. Results are what we want from the system. Typically, in the requirements text, the results are easily distinguished by the following patterns:

• active manifestation - “the system will be”
• passive manifestation - “the correct result of work is ...” or “the incorrect result of work is ...”

Accordingly, the results of the system can link to web pages that display results, reports, and so on. They can also relate to the behavior of the system that we see as users through the interface or in the form of media output (video, for example).
Often a result that is not explicitly not visible is observed by a message that informs the user about what happened. Accordingly, the result of the system may be "nothing." A typical example here is the reaction of the system to hacking or password guessing attempts.
Returning to our requirements. It would be useful for us to see:

• stock percentage
• information that the place is ending

Scenarios (Scenarios)

We finally approached the scenarios (but this is not the end of our work), and now we can combine everything that we dug in the previous stages. At the same time, we pay attention to the following things:

• no branching under the script
• all exceptions are a separate scenario
• the script begins with a description of the starting situation
• the script contains only specific parameter values

(By the way, all this makes the script an excellent test case).
For example,
Initially, the warehouse is empty and can store 100 bags of potatoes, when we add 1 bag of potatoes, we see that the percentage of fullness in the warehouse has become 1%.
Let's move on.

Forecast (Prediction)

We begin to test our scripts for logic. It is always clear how much we get from exactly the result that is described in the script. If not, this most often means that one or another step is skipped, or even not all conditions are described. This returns us to the stage of visualization of the process as a whole.

Ambiguity

(My favorite stage) For this stage it is useful to present the scripts in the form of a table, which then will also find its application.

Customer type	Cart contents	Delivery
VIP	1 book	Free
VIP	10 books	Free
VIP	11 books	Standard
Regular	10 books	Standard
VIP	5 washing machines	Standard
VIP	1 washing machine	5 books Standard

And then we begin to look at the following things:

• are there any cases where the data do not differ or differ slightly, and the result is radically different
• if the case when different data lead to the same result

At this stage, things begin to come up:

• different definitions of one functional
• hidden steps
• ambiguous understanding of terminology
• etc

Spaces (Missing)

In fact, this stage has already implicitly slipped several times, but it is worth mentioning it again. For example, also for the reason that after we got cool scripts, we forgot to update the glossaries, source documents, and so on.
At this stage it is also useful to see a table of scenarios, so it allows you to quickly navigate in them and find spaces.

What's next?

Then we take the BDD framework and start writing code! I’ll talk about this, or rather I will show how this is done in the next webinar. Follow the news!

By the way, here’s the webinar itself about the general theory of the Spec By Example approach