The notion of executable documentation, where a stakeholder’s language is leveraged as a means for decreasing the impedance mismatch between what they want and what they ultimately receive, has, for some time, been ambition of many a development team (and corresponding stakeholders!). While executable documentation proves to be an effective means in assuring customers get what they actually want, this technique also proves to facilitate a deeper level of collaboration between all parties because everyone is using the same language.

For example, the following conversation illustrates a collaborative attempt at defining a new feature– note how, in essence, the conversation tells a story– or more appropriately, a scenario in a story.

Stakeholder: For the upcoming 2.0 release, our VIP customers should receive a discount when they make a purchase.

Developer: What kind of discount– what criteria do they have to meet in order to receive it?

Stakeholder: When they have at least 3 items in their shopping cart, then they receive a 20% discount.

Developer: Does the discount increase based upon the number of items or is it fixed at that percentage?

Stakeholder: The discount is fixed at 20% regardless of the number of items. Consequently, given a VIP customer, when their shopping cart has 3 or more items then they should receive a 20% discount off the total price.

The last statement made by the stakeholder is key– note how they’ve essentially specified the requirement with a means for validating it.

Given their scenario, a developer can literally take the stakeholders comments word for word and execute them via easyb, which facilitates system validation through a domain specific language that supports stories and scenarios as follows:

scenario "VIP customer with 3 items in shopping cart" , {
 given "a VIP customer"
 when "their shopping cart has 3 or more items"
 then "they should receive a 20% discount off the total price"
} 

Of course, this particular scenario doesn’t actually do anything (other than capturing the stakeholder’s requirements); consequently, it is considered pending. This status alone conveys valuable information– a stakeholder can first and foremost, see their words as a means to validate their requests and secondly, they can gauge if their requirement has been fulfilled. Once this scenario has been implemented, it can, of course, take on two other states– those being success or failure, which both serve to convey further status information to interested parties.

Now with a collaborative scenario defined, development can proceed with an implementation– the beauty in this case is that they can directly implement the desired behavior inline with the requirements like so:

scenario "VIP customer with 3 items in shopping cart", {
 given "a VIP customer", {
  customer = new VIPCustomer()
 }
 when "their shopping cart has 3 or more items", {
  customer.shoppingCart << new Item("picture", 50.00)
  customer.shoppingCart << new Item("frame", 10.00)
  customer.shoppingCart << new Item("nails", 1.50)
 }
 then "they should receive a 20% discount off the total price" , {
   customer.orderPrice.shouldBe 49.20
 }
}

Plus, as of the 0.9 release of easyb, the DSL supports two new features: descriptions and narratives, which add detail regarding the features, benefits, and roles of a persona related to a story.

The description syntax that takes a String value or Groovy’s triple quote trick.

description "some description"
scenario "text"

or

description """some long description that requires
multiple lines, etc
"""
scenario "text"

What’s more, you can provide additional details of a story via the narrative syntax:

description "text"

narrative "description", {
 as_a "role"
 i_want "feature"
 so_that "benefit"
}

scenario "text"

Both the narrative and description keywords are optional and they don’t have to be used together– i.e. you can use the narrative one without providing a description. These aspects will be captured in the output (i.e. story report) of an easyb run too.

By leveraging the customers language, the customer has the ability to collaboratively facilitate in validating the system they want built. Plus, with development leveraging the stakeholders language there is a direct link between what stakeholders ask for and what they receive. In fact, given the support of executing scenarios with easyb, I’d say we’re getting really close to truly realizing the hypothesis that one can execute documentation.