This post is from the Collabnet VersionOne blog and has not been updated since the original publish date.
The Clarity of Description
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"] 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.