There is no such thing as a perfect a user story.  There is a spectrum from bad to good for against at least 10 criteria.  I investigate here a single user story relating to a common scenario – the login process.

Authenticating with a software application, or logging in, is found in almost every software application.  It’s such a common feature that most developers will reuse code to implement this functionality.  Yet how often do we think about re-using the requirement?  And how big and complicated is this functionality?  And what does it actually mean when we login?  In this article we will explore these questions and end up with a set of (good quality) re-usable user stories.

A well formed user story will avoid unnecessary discussion, reduce rework and shorten development time significantly, so it is worthwhile to spend time getting the words right.

Let us remember that a user story is written by and for a number of readers for more than one purpose.  The two main messages that a user story should convey are are:

  1. What functionality needs to be developed and who it is for.  (who and what)
  2. To help readers understand why this important (why)

Remember whenever we write something to consider our audience.

Readers of a user story

The different readers of a user story

All of these readers should be able to read the user story and get the same understanding from it.  The readers, may have different goals, and perspectives, but the story should mean the same thing to all readers.  If different readers can interpret the story differently, then consider redrafting it.  In Agile software development  user stories are written as a placeholder for a conversation, yet it is commonplace that user stories are often the only articulation of requirements.  And so it is essential that they are carefully worded.

For the login user story, you might start with the following:

As a user I want to login.

However this leaves a number of questions hanging, like what does “login” actually mean.   What does “user” actually mean?  We might all think we know but the truth is a lot (or a little) can happen behind these words.  Let’s look what might actually happen when we log in to a web application.

A Login Scenario

Here is a typical successful web login scenario:

  1. Enter a username and password.  The username is most often the user’s email address.
  2. Click submit, the username/email is searched.  If found,
  3. an encrypted version of the password is then compared with the stored encrypted version.
  4. The profile is updated with the latest login date time.
  5. The system performs a lookup of groups (or roles) and group memberships,
  6. Finally the user is shown a screen that they are entitled to see based on the outcome of the previous steps.

Now this is a fairly basic scenario, the login process can get much more complicated, for example it could involve federated authentication services, event logging and more, but let’s stick with the simple one for now.

The English language has over 150,000 words we might use, and virtually in any order, so the alternatives are virtually endless.  The purpose of the story is to communicate, and there is no need to be complex if we can express it simply. This is just one version of what the user story might look like:

As a registered_user I can authenticate against my profile. 
The system should also lookup my group_membership. 
It should also retrieve the group [information to determine what features I am permitted to access].

The use of squared brackets helps ScopeMaster to disambiguate the functional interpretation.

Here is the analysis performed by ScopeMaster:

As you can see the functional steps are determined and these are then mapped to Data Movements (the unit of the COSMIC Function Point).

So this version of the story is:

  • User oriented (registered_user presumes that they person should already exist).
  • Valuable
  • Concise (undetailed, referring only to object types, not their individual properties)
  • Complete (describes the key functional steps of this user story)
  • Sizeable –  9 COSMIC Function Points.
  • Unambiguous (successfully mapped to functional steps)
  • No design (it does not specify how it should look nor how it should be coded).

Alternative Paths  (Negative tests)

The other paths also need to be considered within the context of this story, and should probably be added separately as success criteria:

  • My user id is incorrect – display an error message
  • my password doesn’t match – display an error message
  • my password has expired – display an error message
  • my account has been disabled – display an error message
  • I can log in but I am not a member of a role with any permissions – display an error message

Related User Stories

Now that we have covered the basic login user story, we might go on to create stories for the following.

  • Forgotten password
  • Change my password.
  • Store a cookie to remember my identity
  • Administrator can trigger a reset of my password.
  • Register as a user
  • Administrator can register me on my behalf
  • Synchronise or share my id with another authentication system

These will be the subject of future articles, so stay tuned.

I hope you found this useful, please comment below.

Colin.

Be Precise

Spend the time to get the user story right

We analysed over 30,000 user stories at ScopeMaster and estimate, on average every word of a user story describes 25 lines of code,  so a mistake in one word of a user story can have profound impact on development effort and time.