Skip to main content
Enterprise Agile Planning Image

This post is from the Collabnet VersionOne blog and has not been updated since the original publish date.

Last Updated Apr 15, 2014 — Enterprise Agile Planning expert

The Clarity of Description

Enterprise Agile Planning

The User Story, by intent, is meant to be a short definition / an introduction to a discussion.

As a… I can… So that …

Simple, short and powerful. We're all familiar with some variation of this structure and I certainly appreciate the brevity and the focus of the approach. It's an introduction to a conversation, so let's keep the intro light. Here at VersionOne, we've been working on improving the consistency and value of the words we use when defining stories, capturing defects and defining test criteria. From "As a…, I can…, So that…" for user stories to "Given… When… Then…" for acceptance tests, the improvement effort has paid off. We've found our definitions to be shorter, crisper and easier to understand than in years past. Crisp words are great, but they still are not perfect. There are times when even the best words are murky and a more substantial description significantly informs and enhances your conversations. Some cases where this arises include:

  • Focusing on a component of a larger feature, where that larger context is important
  • Conveying errors that are discovered during testing
  • Defining test cases that involve specific data setup

In these cases, robust descriptions that convey imagery and/or tabular data structures strengthen the conversations and help provide a stronger institutional memory. Recent advances in VersionOne's rich text descriptions have provided an even better way of expressing some of the more complex test scenarios we encounter. While I was looking forward to the delivery of these capabilities because they've been highly requested by customers, I must admit that I am surprised at just how much I love the result. Below is an example of an acceptance test with both tabular data and an mocked up image. [caption id="attachment_2631" align="alignright" width="210"]Example Test with Table and Imagery Given, When, Then Acceptance Test[/caption] It would have taken a great many words to describe all of the scenarios covered in this one test. Instead, a table of inputs and a rough image of expected outputs removes the communication issues and allows everyone to focus on the substance of what is being conveyed. Feedback from developers has been great on both the clarity and the expressiveness of such tests. The team has also taken to using the very same scenarios as test data, making it very easy to pinpoint what matches and what doesn't. Such detail is not required on all tests, of course and we certainly do not put more effort into the definition than is helpful. But where there is complexity or visual importance, a table and a picture are incredibly valuable tools to clarify the murkiness.

More from the Blog

View more
Jul 27, 2021

Digital.ai Becomes First to Achieve FedRAMP Moderate “In Process” Status for Enterprise Agile Planning Solution

Enterprise Agile Planning
Digital.ai, the leading AI-driven DevOps value stream delivery, and ma ...
Read More
Jun 21, 2021

How Agile can be implemented effectively across the organization

Enterprise Agile Planning
Just a few decades ago, a “disruption” was seen as an undesirable thin ...
Read More
May 31, 2021

Agile change management processes are key to delivering software faster

Enterprise Agile Planning
With its emphasis on delivery value faster, agile product management s ...
Read More
May 03, 2021

Bringing the agile planning approach to your whole business

Enterprise Agile Planning
The events of the last 12 months have demonstrated that the only sure ...
Read More
Contact Us