Should they be written same way as human workflows, first person "I have entered..." style language etc.? Is the user effectively a gender-less "AI"?

  • Don't put commentary about the site in your questions. We have a meta site that is specifically designated for that purpose here: meta.programmers.stackexchange.com – Robert Harvey Jul 28 '15 at 13:39
  • @RobertHarvey Sorry - done. – Den Jul 28 '15 at 13:41

All software is meant to eventually serve at the behest of some human user, and a user story caters to that. Consequently, any reference in a user story to a machine or other technological item is generally going to be an implementation detail.

Look at this commerce example:

Story: Returns go to stock

In order to keep track of stock
As a store owner
I want to add items back to stock when they're returned

Scenario 1: Refunded items should be returned to stock
Given a customer previously bought a black sweater from me
And I currently have three black sweaters left in stock
When he returns the sweater for a refund
Then I should have four black sweaters in stock

Scenario 2: Replaced items should be returned to stock
Given that a customer buys a blue garment
And I have two blue garments in stock
And three black garments in stock.
When he returns the garment for a replacement in black,
Then I should have three blue garments in stock
And two black garments in stock

Notice that, although the user story is quite detailed, and some "inventory machine" might be involved in the inventory process, that machine is not mentioned in the user story.

Now look at this user story:

As a Creator, I want to upload a video so that any users can view it.

No technology is mentioned. However, if you begin breaking down the user story into more detail:

As a Creator, I want to upload a video from my local machine so that any users can view it.

- The “Upload” button will be a persistent item on every page of the site.
- Videos must not be larger than 100MB, or more than 10 minutes long. 
- File formats can include .flv, .mov, .mp4, .avi, and .mpg.
- Upload progress will be shown in real time.

Now you have the beginning of requirements.

Naturally, nothing prevents you from treating a machine as an actor. If you wish to do that, simply give the machine a general name describing its role, just as you would a person:

As a host machine, I want to collect statistical data to track [some resource] usage.

Further Reading
Using Gherkin to write user stories that will make sense
How to write meaningful User Stories

| improve this answer | |

BDD actually started at a unit level, in which the users of the classes were other classes! So it's perfectly appropriate to have one technical element being the user of another. It doesn't matter whether it's a "class" or a "module" or a "library" or a "service"; the concepts are still the same.

Some of the differences between these two different types of scenarios are:

  • Scenarios are focused on system capabilities, rather than user capabilities
  • Interaction is through the API, rather than the UI
  • The end-goal of the scenarios may be something for another system rather than for a user (though it might be worth phrasing the scenarios in terms of the user value in some situations, such as when the value is immediately consumed).

Some things do remain the same; particularly, talking through scenarios with someone who has the necessary expertise and can tell you what the scenarios need to do. Your conversation might look something like this:

"So, when the data engine gets the new trade, it has to ask the risk calculator to recalculate the risk, then it adjusts the counterparty limits for country, organisation and currency accordingly."

"Can you give me an example?"

"Sure. Let's say we're making a trade with the Belgian arm of a commodity trader for $3m worth of iron, and we're already badly exposed to that trader, and close to the counterparty limit..."

Dan North, who came up with BDD in the first place, likes using 1st person in scenarios as he says it helps him imagine what that person, class, system, etc. must do.

I like using 3rd person, as it helps me work out if there are any missing stakeholders whose outcomes are also important.

Both are valid ways to write scenarios. In the one above, the speaker has automatically used "we" to indicate the organisation. In this case "we" actually represents two systems: the trade booking system, and the system that holds the counterparty limits.

A trade booking system normally has its own UI, but you won't be coding from that level; you'll be going through the data engine's API, as that's the system you're interested in.

Also, the end result of the scenario is still that the counterparty limit is updated. No user will ever get to see that until a relevant report is generated or they get close enough to the limits to trigger an alert.

The phrase, "Can you give me an example?" is still a really easy way to get those examples out of people, as well as the natural language in which they express their requirements... for whatever level those requirements are phrased at.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.