The Power of User Stories

As much as I would like to be consistent with the frequency of this newsletter, unforeseen incidents do cause delays and I can only apologise for it. Hopefully this post covers up for the missed edition and provides some fruitful insights. Before proceeding let us be reminded that we are in the middle of a crisis with Russia invading Ukraine for reasons only logical to a few people in power; all I can do is condemn these attacks on innocent lives of Ukraine and hope the Russian government comes to its senses.

Regarding this article, these past few days I've been following numerous posts discussing User Stories which have become a primary medium of communicating a product's requirements. Partly driven by the Agile Software Development movement and partly by the Managerial Tools, User Stories have become a part of our daily vocabulary. It's usage however arguably isn't been the most appropriate with many teams who I've interacted with. I have posted about Good & Bad User Stories in the past, this post however is an attempt to share an example that one can utilise with their teams to unleash the true power of User Stories.

Starting with the obvious

Regardless of the teams I've interacted with or the products I've seen get built, there's almost always a Login User Story. Before we begin judging this statement, let's look at a User Story that would typically convey this product requirement. As a context, the User Story below is from one of my earlier products which was developed for a Book Publishing Workflow; the product was built on Documentum xCP and heavily utilised the underlying mechanisms of the tool. I use Gherkin for my User Stories and one can check this reference in case any help is needed understanding the syntax.

During the time of building this product, when I provided this User Story to my team it hardly faced any resistance (apart from a lot more test cases that were needed for the last scenario). As a few commenters also stated in various similar posts, this User Story is very straight forward and provides the necessary details needed by the developers to implement the requirement. Given I was the author in this context on this product, I wouldn't argue either that this User Story needs any improvement. I will provide another example though in a different context.

The not so obvious

My team and I were building a Proof of Concept (POC) of a Peer Review System for Scientific Publishing. This product was also being built on Documentum xCP and heavily utilised the underlying mechanisms of the tool, only this time it had an external facade built in Angular as a public facing website. One of the primary users were the Authors who wanted to publish their research in a Scientific Journal. Authors would typically want to see the progress of their articles from peer review through publishing and hence required to login to a system for the necessary details. My team included me - the Business Analyst (BA), two Full-Stack Developers (FSD1 & FSD2), a Documentum Specialist (DS), and a Quality Analyst (QA). Here's what happened.

The story came up for discussion, it simply mentioned this

As an Author, I want to authenticate myself to view my submitted articles and their progress

FSD1: What do we use for authentication, the default Documentum User Profiles?

DS: I don't think using Documentum User Profiles will be appropriate, every user created in Documentum attracts a user license. We can have thousand's of Authors who submit only once into the system but we'll have to pay their licenses forever which becomes an unnecessary running cost.

FSD2: Can't we delete the user once their article has been published to save the costs?

BA: We can but we'll still need to maintain their data somehow because we need to track returning Authors. Plus we shouldn't ask an Author to create an account every time they wish to submit an article, we do that currently with each of our journals and it really pisses them off. That's an experience we definitely need to improve.

FSD1: Okay, so we need to create a common Identity mechanism to authenticate an Author across the journals?

BA: Not really, in production, we can use ORCID wherever possible but for the sake of this POC, we should have a mechanism to identify an author so we can list their submissions.

QA: So why do they need to authenticate? It's basically we who wants to identify them and show them the submitted article's status.

FSD1: What's the difference?

QA: The author doesn't really want to authenticate themselves, that's of no value to them. They just wish to see their articles' status and contact the Editor if needed, for instance if they wish to withdraw the submitted article. It's we, the Publisher, who wants to know who they are so we can show only their articles to them.

FSD2: So what are you suggesting, we need to identify the Author but don't really need to maintain any data needed for authenticating them?

QA: We'll still need to maintain sessions but yes we wouldn't need any persistent storage. Question is how do we do that?

DS: We can use a Magic Link!

FSD2: A what now?

BA: A Magic Link. It works a little like SMS authentication via OTP, you enter your email address, receive a one time link and when clicked, you're authenticated. Plus we rely on the security of the email service provider which very like will be secure.

FSD1: So how do we test it? Like some kind of Forgot Password?

QA: You can say that. Send a random hashed token that expires in 30 minutes or when access is attempted, whichever is earlier.

This discussion around Acceptance Tests went on for a while and we finally arrived at the below User Story.

A few more scenarios (zero submissions, logging, etc.) and we were good with this implementation. So what's so great about this User Story that unleashes its true power which the former couldn't? I'll go out a limb and call out that both User Stories are written correctly; I'll present a case against this in the Beyond Conclusion section of this post but for now let's say that there's absolutely now flaws in the way these User Stories have been written. The power of a User Story doesn't lay in the way it's written, it lies in the process.

User Story as a Process

Alistair Cockburn famously coined the phrase

A user story is a promise for a conversation

Ron Jefferies popularised this by defining the 3 C's, Card-Conversation-Confirmation. This is what differentiates User Stories from other forms of Requirements Specification formats. As seen in my first case, although the User Story was written well, it was written in isolation, by me. It was discussed with the team afterwards and the team pretty much agreed to it, but we will never know how that story would have turned out in case in was written as a team like in the second case.

If we pay close attention to the second case, we'll realise that although the User Story very much began with the notion of an Author wanting to authenticate themself, my team very quickly realised that authentication wasn't the true value that the Author wished to achieve. They only wished to view & monitor their article submissions and a form of identification just became a means to reach their greater goal. This also led to selecting an authentication mechanism that did not rely on the usual username / password schema and resulted in reduced storage requirements & maintenance for my team.

The Card-Conversation-Confirmation process keeps the scope small (Card done in a week), allows the team members to talk about the requirements for clarity that fosters shared understanding as opposed to the ambiguity that can be created by ONLY reading documents, and leads to the identification of Acceptance Tests needed to confirm the completion of the desired functionality. This is a power no documentation strategy can provide. In fact, if implemented well, once a User Story is completed, the teams can very much tear up the Cards (or delete the Jira tickets); User Stories are not long living documents since they are Negotiable and are going to change as the system evolves. If one still looking for the requirements specification, they exist in the Automated Acceptance Tests aka Tests as Specifications or Specification by Examples.

It's very easy to mess this up though. Since User Stories don't have a fixed format, many go to town with it. The description starts including system behaviour in clicks and scrolls, context & assumptions get added, stories start getting linked to each other in tools like Jira, all-in-all taking the shape of any other documentation format and killing the essence of a User Story. But that's probably a story for another article. For now ...

In Conclusion: Long story Short

User Stories are so far the most amazing way to develop software and although better ways may be found in the future, these would still remain a worthy contender. As seen however, it's very easy to neglect its full potential and hence a level of discipline is needed to stop using it as a documentation mechanism. Hope this article shed some light towards the Power of User Stories.

Beyond Conclusion

It's probably important to mention that User Authentication are one of the most valueless User Stories ever. It's not in the way it's written, it's the way it exists as a user behaviour in the real world.

Let's consider that we're the proud owner of a smart phone. This phone has our favourite email application installed. How would we feel as a user of this smart phone if we're prompted to enter our username and password (may be a two factor authentication code) every time we wished to access our email? That probably would be the most unsatisfying user experience given that we access our emails many times a day. So if this is an unacceptable behaviour for us, why should a User Story exist in a product's backlog that mimics,

As a Business Person, I want to authenticate myself so that I can read my emails

For the sake of argument, let's say that this is because it is only I and I who can read my emails and no one else. And authentication on phone may not be needed since phone’s have locks too. However our phone locks are optional and even if we have biometric authentication on our phones, these are overridden by pattern or number locks which are much less entropic than email passwords. So even if we are paranoid to ensure that our emails are accessible only to us, our phones only care for it up to a million permutations.

There are applications though where various forms of recurring authentication is needed, for e.g. banking. Here as well though, it's more about securing various transactions from fraud rather than a user wanting to prove their identity. Which brings us to a question, is authentication even necessary from a user's point of view? May be not! But it is absolutely essential from a provider's point of view. Gmail for example needs to know who we are so it can show us only our emails and no one else's whereas HSBC needs to know who we so they can provide us access to our money for usage. Regardless of the provider, what probably makes more sense is to consider authentication as not just a User Story in our product backlog, rather as a System Wide Constraint, a Non-Functional / Cross-Functional requirement.

So next time we hear about User Authentication, it's basically an opportunity to have a much larger discussion about our Threat Modeling & Security Strategies. These discussions can very well flow like the discussions around any User Stories however its value & impact will definitely not be limited to a single User Story.

As HSBC, I want to authenticate my customers so that I can restrict unauthorised access to their accounts