What is the best way to write user scenarios for developers to remove ambiguity?

Question

At the company I work for I implemented the following format because a lot of the time the User Scenarios were just too ambiguous and developers would often need to get in touch with the product team to clarify how exactly things should work or even worse they would just decide themselves how it should work.

User Story

As a user of the archive
I want to be able to send an archived email to my personal mailbox
so that I can take action on an email that may no longer exist in my personal mailbox

Scenario Example

1. User Clicks on Forward (Anchor 1) within Search Results Panel 1
2. System returns Confirmation Modal 1 containing Form 2
3. User fills in Form 2 with their own email address and clicks "Send"(Submit Button 2)
4. System returns Success Modal 1 which fades out (See Animation 1)
5. System returns Archive Search Page containing Search Results Inbox with Search Results Panel 1

Each of these scenarios are accompanied with Invision walkthroughs, animations etc

Then all of the elements detailed above are referenced in categories below accompanied with individual static images outlining measurements and specification information for any new HTML elements.

The categories are as follows:

• Pages
• Panels
• Tables
• Forms
• Modals
• Alerts

My question is, is this the best way to do this or can anyone recommend a better way of supplying documentation to developers?

Answer 1

User Stories should be written like that - they are short and very focused on the essence of the feature. I prefer Jeff Patton's approach in his book User Story Mapping.

However, Agile practitioners tend not to like documentation, yet there is so much detail in a user interface and the interaction between the user and the user interface, sometimes some level of 'documentation' can still be helpful.

Design tools like Axure or Balsamiq, etc can now quickly demonstrate interactive behaviour so can reduce how much you need to explain in other forms. Axure allows you to produce flow diagrams and add notes to UI elements, and it can also generate documentation from your design if you really need it.

Ultimately this is nothing more than a communication problem, e.g. how to communicate your design intentions, and it will vary from one company to another.

Ideally you will be co-located with the developers, so it it should be fairly easy to pick the right way of working closely with your development team.

Also remember that design is not something you do on your own - it is a collaboration between you and the developers.

Answer 2

Have you thought about using BDD language (Given, When, Then... and its variants Cucumber and Gherkin) to specify your scenarios?

Scenario: Eric wants to withdraw money from his bank account at an ATM

Given Eric has a valid Credit or Debit card
And his account balance is $100
When he inserts his card
And withdraws $45
Then the ATM should return $45
And his account balance is $55

This ties nicely in with automated testing frameworks if your team is interested in that too.

https://en.wikipedia.org/wiki/Behavior-driven_development https://en.wikipedia.org/wiki/Cucumber_(software)

Answer 3

I'd like to stress an aspect that was mentioned several times - Design is a communcation task. First, it's communication with users, then it's communication with developers (and in between, it's communication with the project manager :-).

What I mean by that is - no form of documentation will remove all ambiguity. Designers need to talk to developers not only about the design, but also about their intentions. Ideally, developers already participate in the user research.

Your sentence "developers would often need to get in touch with the product team to clarify" sounds a little like it's the developer's task to find out what the designers wanted. This is not user-centered methodology, rather the opposite. In my view, the designer should not only think about product users when creating the design, but also think about design spec users (i.e., developers) when communicating the design.

I find it interesting that designers sometimes apply user-centered methods only for the product design. Why not use the same mindset when communicating internally? Make your design as accessible as possible for developers, and you'll get more usage (that's the same as ensuring all product features are accessible to the user).

Coming back to your question, I think there is no way around regular (call it iterative) talking to your developers - from user research to product launch.