getting the balance right between SBEs and other product documentation

Question

Reading online material (e.g. Fowler, Gerard), it seems that Specification By Example stories should not be complete specifications of functionality.

Question 1: How does one starting off with SBE's decide how comprehensive their stories need to be in terms of describing all of the functionality of a system? I.e. when can I stop writing stories because I have captured enough?

Question 2: In an organisation where test teams verify products against the product documentation, if the stores are not a complete specification, am I correct in thinking that 'other' product documentation needs to contain all the cases that are not covered by the SBE's?

Answer 1

Regarding question 1:

The most important part of developing any system is that the development team has a conversation with the product owner. First find out the crux of the feature which they require. I'll answer this question by working through an example; let us say that the product owner may want a facility to login to their new website. This requirement could be written as:

In order to gain access to the website's facilities
As a user
I want to be able to login to the website

(Note that I'm using the Gherkin domain specific language for writing the scenarios and features in this answer)

With the product owner's key requirement specified, you should now discuss with them how you think this feature should be implemeneted from a users perspective (keep it high-level, don't use technical jargon, discuss with the business to find out what they want). So the first "happy path" scenario you might identify could be:

Given a user is on the login screen
When they submit valid login credentials
Then they gain access to the main website

After further discussion with the product owner they tell you that as the website contains extremely sensitive information, and that any failed log-in attempts should be reported to a system administrator. This would result in another scenario:

Given a user is on the login screen
When they submit invalid login credentials
Then the system administrator is informed of the failed log-in attempt
And the user is informed that their login attempt failed

At this point the product owner might say that these are the only scenarios they want for logging into the system. So from the development teams perspective no more investigation would need to be done regarding this feature (so you wouldn't need to write any more user stories). Sure, at a later point in the projects development, the product owner might also tell you that they'd like to inform a user when they last logged into their site before reaching the main website, but you'd only need to worry about this when they ask for it.

Regarding question 2:

The organisation should be verifying the products against "living" documentation e.g. using Cucumber(for example) which generates tests from the scenarios detailed above.

Also as I said in the answer to question 1, you should identify "just enough" of the scenarios/use cases to satisfy the product owner. What the product owner asks for is the complete specification. Don't try and second guess what the product owner might want because this may result in be a classic case of YAGNI.