Getting clients, managers, project managers, designers, and developers on the same page when it comes to feature expectations is hard. Everyone speaking the same language (literally) can go a long way to achieving the same, metaphorically.
There are three common formats that are great for written and verbal communication between stakeholders with different backgrounds, responsibilities, and risk exposures. They are each natural-language, narrative formats (they use plain english) that anyone can understand, but their structrued nature is proven to help clearly communicate behavior, specify intent and synchronize expectations.
- Great for high level feature description
- Typically bad for detailed behavior description
As a User, I want to be able to type in a search, so that I can easily find the vehicle I'm thinking of.
This 3 part format helps specify stakeholder context, as well as delineate feature/behavior and benefit/intent separately, while still remaining very lightweight and usable. Understanding context, behavior, and intent are critical for the different disciplines involved in product development.
The simple use of this format early on in the research and develoment stages can help to syncronize understanding of specifically what is agreed to without specifying too much detail for early stages. Ensuring that high-level requirements be distilled and reduced to this simple format can protect both client and provider in future development cycles, and can help identify communication break-downs early.
As (stakeholder context for narrative)
I want (description of feature)
So that (benefit of feature)
- Great for detailed scenario and behavior description
- Sometimes good for more complex high level scenario description
- Rarely good for very complex/interconnected or algorithmic behavior
Given I'm on the homepage, when I search for a stock number, then I see the vehicles with that stock number.
This three-part format specifies context, action, and expected results to fully describe behavior. This format can be extended as shown below to describe both simple and more complex behaviors with equal simplicity. This language helps nail down expectations and significantly reduce iteration on a behavior's design, implementation, and testing as many extra iterations and frustrations commonly result from simple miscommunication from different stakeholders.
Extremely useful for design and implementation stages, this format can be a workhorse for helping creatives, technicals and non-technicals clearly communicate around behavior through the product development process. This format is also ideally used to report bugs, drastically reducing communication iterations to reproduce and fix a reported issue.
- Given (context or scenario for narrative)
- When (description of behavior)
- Then (reason behavior is important)
Note: Each of the three parts of a gherkin narrative can be extended cleanly with one or more And or But clauses.
Given I'm logged in And I'm on the homepage When I click sign out Then I'm still on the homepage But I don't see my username in the header And I see 'sign in' in the header
- Great for complex or highly interconnected business logic or algorithmic behavior
- Avoid for high level stories and scenarios, as it presents many risks
Once you have alpplied a few filters to a vehicle search, such that the result is a smaller set of vehicles, we should not show a filter if selecting it would hide all vehicles; nor should we show a filter if it doesn't apply to any of the vehicles in the current search.
Trying to describe very specific, complex, or low-level behavior with a user story or Gherkin narrative can be very cumbersome to write, and even more awkward to read. The above example isn't a perfect one, as the Gherkin narrative for it might be more appropriate. Imagine describing the calculation of the possible next moves in a game of chess, or the scoring of a turn of Mastermind, where there are many interconnected behaviors to describe at once.
Using free-form prose should be a last resort, as it carries with it the most risk. Misunderstanding and miscommunication can happen easily due to the lack of structure. A recommendation is to attempt to only use this format when the other narrative formats will not allow clear communication, and to only use it for very specific or complex descriptions.