Delightful Requirements: Seeking the sweet spot

The goal when writing requirements in Gherkin for automation can be expressed this way:

It is the quest for the sweet-spot between lucid language and efficient test implementation.  

If we focus on just one goal without the other, we will frustrate one of our primary audiences.

Writing for business users only

We might write Gherkin scenarios that communicate effectively to the business user, but are not readily implemented by a developer.  For example, consider this scenario:

Scenario: Widgets must have ISO Standard temporal flubargle settings
  When a widget has incorrect temporal flubargle settings according to ISO 5432
  Then that is an unacceptable widget

The business user might like this requirement very much.  But, the developer implementing the test will have a multitude of unanswered questions:  What are correct and incorrect temporal flubargle settings?  What action is being evaluated in this test?  What does it mean for the widget to be unacceptable?  What behavior should the system exhibit for an unacceptable widget?

Writing for developers only

Even worse, we might write Gherkin scenarios that are tailored for the developer, but are incomprehensible for a business user.  For example:

Scenario: Widgets must have valid CF_101 and RV_999 values
  Given a widget entity with these fields:
    | CF_101    | RV_999 |
    | 10-2-2015 | 33     |
  When I POST that entity
  Then the HTTP status code should be 400

If you write API code for a living, you can probably picture how to implement that test.  But, the business user will need every clause of that scenario interpreted for him.  That will seriously inhibit the meaningful conversation a scenario is intended to initiate.

Writing for both audiences

Requirements writers earn their keep when they keep implementation in mind while they write in the language of the business user.   

Perhaps the scenario could be worded this way to serve both audiences:

Scenario: Widgets must have ISO Standard temporal flubargle settings
  Given this widget:
    | Sample Date | Flubargle Value |
    | 10-2-2015   | 33              |
  When I attempt to create this widget
  Then I should be prevented from adding this invalid widget

The search for the ideal balance has few absolute rules.  The right balance for one organization may differ from another organization.  The important thing is the constant focus on serving both needs.