Improving the login user story - authenticating and authorising

There is more to the login the user story than you might think. Behind a two field entry can lie significant processing and complexity, so it’s really important to spend time getting the words right. To start with, the wording should be clear, unambiguous, consistent, concise yet also complete.

There is no such thing as a perfect a user story. There is a spectrum of quality, from bad to good. And user story quality can be assessed against at least 10 criteria. I investigate here a single user story relating to a common scenario – the login process – and see how we can move along the quality line.

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 try to 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.

Be Precise

Spend the time to get the user story right

We analysed over 100,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.

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 for a number of readers and for more than one purpose. The two main messages that a user story should convey are are:

Who is the user and what functionality do they need. (who and what)
Why is this important (why)

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

As a user I want to login.

But this is a poor user story and we will explain why. This leaves a number of questions unanswered, what does “login” actually mean. What does “user” actually mean? We might all think we know what these terms mean, but it pays to look more closely, in fact a lot might need to take place behind the scenes, when authenticating with an application. 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:

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

Use case model diagram generated by ScopeMaster for the Login user story

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].

Analysing the functional steps of user stories

Here is the detailed analysis performed by ScopeMaster:

The use of squared brackets tells ScopeMaster to ignore some text when determining functional meaning.

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 much better because it is:

User oriented (registered_user presumes that they person should already exist).
Valuable
Concise (un-detailed, referring only to object types, not their individual properties)
Complete (describes all the key functional steps of this user story)
Sizeable, at 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).

Further considerations. 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

Consider your audience

Spend the time to get the user story right

Consider the audience for your 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.