How to Document Your Designs Using Behavior Driven User Stories

A common issue when documenting requirements is taking a stand from the system perspective to describe what is needed, forgetting that it’s the user who will be at the center of the interactions. User stories, introduced by Agile, tackle this issue by making the user the center of the requirement, and Behavior Driven Development (BDD) takes things a step further providing a framework where the user behavior is what drives the development.

Using BDD techniques to create user stories makes documenting requirements easier to write and read. Also, it provides additional tools to communicate the intended user experience of a design, that designers, developers, and QA engineers can use to fast track and even automate part of their work. In this article I will explore this approach and show how you can use it to document your own designs, starting from small stories to organizing those stories for communicating fully functional features.

UI Requirements vs UX Requirements

There is an important distinction to make between UI requirements (also known as specifications) and UX requirements. On the one hand, UI requirements are technical documents that list specifics about the user interface, including font types, colors, dimensions and layout of elements. A good example of this type of documentation are Living Style Guides.

UX requirements, on the other hand, describe what the experience should be for a specific user, given that this user is in a specific scenario doing a specific action. A user story can capture a UX requirement in a very succinct way. For example:

• 
  As a.. publisher user,


• 
  I want to.. be able to review articles before they are published,


• 
  So that.. I can provide feedback and ensure quality in a timely manner.

This story indicates first the user’s role, what this user wants to accomplish, and then explains the reason behind it. This is great as it provides insight to developers and testers of what the ultimate goal is: to suffice a user need. Note that the words in bold are the template used to write the story. There is always a user, that wants to do something, so that they can accomplish a specific goal. You can follow these tips for writing good user stories.

With this story in mind, the design team may decide that an “approval” action is needed to accomplish the user’s goal. Then to provide specifics on how this will actually work, you can use Gherkin syntax, which is a BBD tool for writing business readable requirements. Gherkin syntax is similar to agile user stories as it provides a way of writing requirements that can also be used as a template. The advantage is that you can get into more specifics, providing scenarios and actions that the user would take without getting into how the implementation should be done. Let’s take a close look at it.

Writing User Stories Using Gherkin Syntax

The basics of a story using Gherkin Syntax can be summarized in these parts:

• A feature


• A scenario


• A precondition


• An action


• An outcome

A feature is a place to describe the overall business value of the implementation. It can also be used to provide additional information, such as business rules, or anything that make the feature easier to understand (such as links to prototypes or UI requirements).

A scenario describes the specific circumstances in which the user is. From a user design perspective, scenarios allow communicating the multiple variables of a design, and how the UI should handle those, according to the user.

A precondition helps build up the scenario and removes any ambiguity. For example, in a scenario that describes a first time user accessing a particular screen, the precondition can clarify that the user is logged in.

An action indicates exactly what the user does in the interface, and is typically a “trigger”, such as clicking on a button, submitting a form, or navigating to another place.

An outcome is the consequence of the action, and should always be something that can be tested.

With these parts in mind, let’s write a user story for the feature that we described earlier:

• 
  As a.. publisher user,


• 
  I want to.. be able to review articles before they are published,


• 
  So that.. I can provide feedback and ensure quality in a timely manner.

Using Gherkin Syntax this story would look like this:

You can see how the initial story turns into a more detailed flow that the user can follow and therefore that can be tested. Also, note that the words in bold are the keywords that software such as cucumber uses to automate the execution of tests. I will explain more about this later on, but for now, I want to point out that these keywords are very helpful as well for writing the story because they help distinguish the different parts of the story.

Something else to point out is that although the story provides more details about the user flow, the interface is not described. The reason for this is that describing the UI can quickly turn the story into UI requirements, which presents a big problem as they can get outdated rather quickly. For example, if the story describes how the success alert looks like and what the specific message should say, then the story can get out of sync if any of this changes, creating the potential of tests failing.

So the trick is to provide enough detail, without doing the job of more adequate tools, such as design mockups, prototypes, and style guides. In this respect, you will notice that the action does indicate “selecting approve” vs. just using “approving”. “Selecting approve” is not specific as to what this control looks like (it could be a button, a button that looks like a link, or a box that is clickable), but it does imply that an element in the UI is triggered. It also indicates that is this element has written in it “approve”. This is a gray area where you will need to use common sense, as in some cases you will want to be this specific so that actions can be distinguished from others. For example, if there is another way of approving an article on the same page, indicating that in this scenario the user has to “select” it, allows making the differentiation.

The Importance of Scenarios

Besides the thoughtful syntax that Gherkin provides, one of the things I find most useful is using the “scenarios” part. Scenarios are powerful because they can be used to test the design and make sure all of the bases are covered.

Usually, designs of any kind start with the “happy path”, meaning what happens when everything goes well in the interface, and how it applies to the majority of users. In our previous example we had:

Also, because we know that articles have publishing dates, we can also state: This is our first scenario because in the majority of cases articles that need to be approved should be ready for publishing. But this brings the question: what happens when an article is not ready for publishing and the publisher accesses it? Should they even be able to access those articles?

• What would happen if an article that is approved has a publishing date in the past? Should the article be published immediately, or should they go into a queue? 


• And going a step further, what if a publisher approves an article by mistake? What is the procedure for undoing this action? Who should get notified?

All of these questions are part of the design process and most likely by the time you jump into documentation requirements you will know the answers. The great news is that using scenarios in your story documentation will help you structure them and in many cases will help you QA your own designs, making sure there is a design and flow intended for each of them.

Let’s see how our story would take shape with the additional scenarios:

Depending on the feature, there can be many scenarios to consider. They key is to keep them short, so that you can describe and test them easily. You can also try grouping them, using common denominators. For example, if a few scenarios share the same precondition, you can encapsulate this into a “Background” that can be used by multiple scenarios. For example:

Organizing Stories to Communicate a Feature

A common challenge that arises when documenting requirements is in deciding which order to do it. The reason being that in most cases everything is under construction, which makes hard to test an interaction when the parts of the interactions are not yet built. For example, in the simple interaction of “approving” an article, many things need to be ready:

1. The UI should be able to return a success message if the approval is successful and a failure message in case there is a system problem.


2. The UI should be able to “tag” articles as approved.


3. The UI should be able to display the article according to the “published” business logic.


4. System notifications should be enabled, so writers can get alerted when the approval occurs.

An approach to documenting requirements for each of these dependencies it to record them as different features that can then be prioritized according to their business value.

Then you can create an “integration” story to bring all them together. For example, a user story for the tagging system would like this:

In the integration story, you can reference the tagging story, in the case that the details for that scenario need to be verified again or if you simply want to know if those cases have been already verified.

The point is to avoid repeating documentation that not only consumes time unnecessarily, but also that can become out of sync.

Turning the User Stories Into Test Cases

We have seen how useful Behavioral Driven User Stories can be for writing requirements that are focused, concise, but also thorough and descriptive. Starting from the design phase, this tool can lend a good primer for QA engineers for writing actual test cases.

Besides these great advantages, Behavioral Driven User Stories can actually be turned into functional tests with the help of software, such as Cucumber or Lettuce. The basic idea is that once the stories are written using Gherkin syntax, you can place them in a .feature file inside of your app, and then run them as tests to show if they were successful or not.  For an in-depth tutorial on how to use Lettuce for a Python implementation check David Sale’s tutorial:

• 
  Python
  
  
  Behavior-Driven Development in Python
  
  
  David Sale

Conclusion

Writing user stories using the principles of BDD can serve to communicate in detail business and design requirements, with a user-centric approach, while using a language that is human readable but extendable for software interpretation. Additionally it can be used to test:

• your own designs as you document requirements


• the actual application manually, once turned into test cases by a QA engineer


• the actual application automatically, when turned into functional tests using BDD software.

This means more layers for bugs to go through, preventing gaps in the design and further bulletproofing your application from bug failures.