Good analysis documentation should be understandable for the client, the development team, and the testers. These groups have different scopes of competence and therefore use different language codes. A major challenge for the analysis teams is to describe the requirements in such a way that none of these groups has any doubts about the purpose of the project/change and to leave no room for free interpretation. Meeting these requirements is often not an easy task and presents analysts with specific challenges.

Can the Gherkin language help analysts in their work?
Let's start with a question about imperfections of classic and commonly used methods: Use Case, or User Stories used in agile methods. After all, they can be used to create a perfect analysis that leaves no room for doubt, and Use Case integrates beautifully with UML notation.

However, it should be noted that these methods allow quite a lot of freedom to scale the precision, which is especially true for User Stories, for which the description template is very general. Therefore, a lot depends here on the experience of the analyst, who has to assess which aspects should be described in detail and which can remain more general, because their precision is not so important for the success of the project.
This aspect can therefore pose some problems for less experienced analysts, who are not always able to correctly predict how another team member will understand a given scenario and where less precise descriptions can actually be afforded. This is why the following advice is sometimes given to novices:

"if you don't know where you can spare the details, then just describe everything in detail''
or in an iterative approach:
"describe everything in general terms for now and then we will see what needs to be specified".

So, back to the question in the title - let's consider whether and to what extent the Gherkin language can help create better documentation?

What is Gherkin?

It is a natural language, in many ways similar to its big brothers mentioned above. However, it introduces some rather narrow frameworks and defines how they should be filled with content. It has keywords that define the template of the language:
Feature - name of the described functionality
Scenario - name of the scenario under consideration (equivalent to use case/user story name); under the title, it is sometimes useful to add a general description of the scenario to give some context
Given - defines the initial condition, a very specific one, e.g. what properties an object has before the start of the scenario (to some extent it is the equivalent of the precondition from the use case. User story has no equivalent).
When - defines the condition for starting the scenario (equivalent to trigger in use case) - Then - scenario action, describes what happens in the scenario (equivalent to Basic flow in a use case)
And - a keyword that can occur in combination with Given, When and Then, which can be used to combine conditions into a string marked with an "and". That is, if a definition requires several conditions to take place simultaneously, we can use "And".

Up to this point, as you can see, this is actually nothing new, as similar equivalents already exist in the Use Case method. However, the difference is in the details on which the Gherkin language is based. To understand them better, it is worth mentioning the history of this language. Gherkin was not necessarily developed for analysts, but rather for testers. Its origin comes from the Cucumber application released in 2018, which is used to automate acceptance tests based on the Behavior-Driven Development (BDD) process. The Gherkin language was invented with this solution in mind precisely to make tests more understandable for all stakeholders.

This origin obliges us to use the Gherkin notation in the same way as it would be used in the Cucamber application. Each scenario must be based on precise descriptions, because we cannot simply write e.g. "If product X is available then...", because in a test scenario this will not work, because what does it actually mean that "it is available"? In this case the notation must be precise e.g. "When product X has active status and its available quantity is >= 1 then...". That's better, right? This description, as we can see, is still a natural description, which is understandable for the client, but it has the property that it is also automatically unambiguous for the tester as well as the programmer. Obviously, the names of the properties themselves, such as "available quantity" is not necessarily the same as the name of a column in the database, or the name of a field in the application class, but it is precise enough to leave no doubt about its meaning, and in this sense meets the expectations of good analysis.

What do we gain beyond the unambiguity described above? Detail. Detail, which sometimes can also be a disadvantage of this solution. It is impossible to make a test scenario in Gherkin that is both general and follows the rules of the language. Is then still the only solution to describe everything in detail? Not necessarily. Here again, it is worth returning to the origin. Does every, even minor, area of the application require acceptance scenarios? No, after all, testers do not necessarily test whether, for example, the button itself reacts to a click, it is, after all, about confident behaviour (Behavior-D.D.). So if we want to use this language while developing the analysis, we should not create scenarios for unimportant functions at all. In this case, it is worth considering leaving a general description instead of building a scenario.

An experienced analyst will now probably point out that this way of documenting will certainly require more time - and he will be right. Gherkin is much more absorbing. What in Use Case can be included in one scenario as Alternative Flows, in Gherkin requires a separate scenario. But overall, this workload will more than pay for itself. If the analyst prepares BDD-compliant scenarios in advance, the tester will not have to do so. In addition, the testers will test exactly what is written in the analysis document instead of using their own interpretation, which can save a lot of misunderstandings.

Below is an example scenario using Gherkin notation.

Feature 1: Promotional codes

Scenario 1: Validation-code active, add promo code to order

Given the client is on the order summary page 
And there is a <PROMOTION CODE> in <STATUS> active in the system 
When the user enters the <PROMOTION CODE> in the Promo Code field 
And confirms the operation
Then the system will check if it has a <PROMOTIONAL CODE>.
And will confirm if the < PROMOTIONAL CODE> has <STATUS> active.
And will retrieve information about <CODE VALUE>.
And will display that a <PROMOTION CODE> for <CODE VALUE> has been added to your order.

Examples: (The values of the corresponding columns should be substituted under 'placeholders' marked with <COLUMN NAME>.)
| PROMO CODE   | CODE VALUE | STATUS |
| Promotion1   | 10.00      | ACTIVE |
| AZK6IKT21MCM | 20.00      | ACTIVE |

Scenario 2: Validation-Code not active, error message.

Summary
Every method, including Gherkin, has certain advantages, but also drawbacks, so its selection should depend on the specific case.

Advantages of introducing Gherkin notation:

• More precise description of requirements in the analysis document
• Greater certainty that the resulting project will meet client expectations
• Less time spent on detailing requirements during project implementation
• Possibility to use the same scenarios at the reception stage as in the analytical document

Disadvantages of Gherkin notation:

• The more labor-intensive analysis phase
• More difficult to learn notation and rules for the correct formulation of scenarios
• When can using Gherkin notation be a good alternative in a project?
• Is the current analysis so general that different groups of workers interpret its provisions differently?
• Does the project currently have an automated acceptance testing process?
• Does the project have processes of exceptional complexity that must be described in great detail at the analysis stage?
• Is it challenging to formally change the findings after the analysis stage?

An affirmative answer to the above questions is an indication to use the Gherkin method.