If you work in IT or security, you are pretty much expected to know what a user story is. That can be a problem if your background is not in software development, or if your education or background predates the agile software development model. So what is a user story and how do you write one?

User stories are similar to milestones in project management. That was how it was first explained to me. But you don’t write a user story quite the same way that you would write a milestone in project management. The other thing is mixing the two can lead to miscommunication. I was once involved in a meeting where a manager insisted on using user stories, because he had been a software developer, but this wasn’t a project involving software development. So nobody else knew what he was talking about.

User stories are a product management or software development tool. They aren’t something everyone knows.

What a user story is, in software development or product management

what is a user story

Sometimes reading bad user stories can help you write good ones. @S–tUserStory on Twitter is a good account to follow for that, if you’re not offended by lots of profanity.

Whether you’re dealing with product management or software development, a user story answers three questions: who, what, and why. It can be as short as three sentences. But each of the three components can be as short or as long as necessary. Sometimes the second and third sections can be quite a bit longer.

When you are sending a feature request to a software vendor, sometimes they want the request in the form of a user story. So it can be helpful to be able to write a user story even if you aren’t a developer.

Pro tip: when working with a vendor, the more closely you follow the format they are used to, and the more you present the request as a win-win, the better your chance is of getting the approval.

Sometimes flexing backfires. Even if your name is Walmart, don’t expect that you are the vendor’s largest customer in terms of revenue. You may be the biggest company on the Fortune index, but if the company right behind you has more systems because of the business they are in, or if they buy more products from the vendor than you do, you’re not necessarily their highest priority. A win-win attitude makes it much more likely you will get what you want. Or something close.

Components of a user story

Here are the components of a user story:
As a blank
I want to blank
So that I can blank

A memorable user story example

Here is a joke user story that circulated after Facebook decided to clone Google Glass a decade after Google Glass failed in the marketplace.

As a Facebook user
I want virtual reality goggles
So that I can work from home and attend a virtual meeting that could have been an email

You can add a couple more sections to the end of the user story to add more detail. Some useful information can include relevant API calls if you are trying to make one product work with another, or an outline or an algorithm.

I once got a feature request approved largely by providing a simple algorithm that would accomplish what I wanted. Since all the developer had to do was write a few lines of PHP based on the algorithm I provided, and what I was asking for wasn’t terribly complicated, my feature request made it into the product’s next release.

My user story that led to a successful feature request

Here is my successful feature request, rewritten user story form.

As a security analyst
I want an authentication test feature
So that I can quickly test and troubleshoot authentication records without having to run a full scan, download the results, and analyze a CSV file. A similar feature exists in your two leading competitors, so this will bring your product to closer feature parity with them, and will also reduce support calls because it will be possible for end users to do their own troubleshooting rather than asking why they’re scans are failing to authenticate.

I am able to approximate this feature by creating a scan profile with the authentication checks for Windows and SSH and no others, but it would be much easier if you were to provide a checkbox in the scan options that automatically perform this cut down scan and then presented the results when it finished.

Why this user story was successful

It’s not always possible to provide an algorithm with that kind of knowledge, but at least providing an outline can be helpful. Lo and behold, The feature I described in this user story appeared in the very next product release. And it was implemented almost exactly the way I described. I think the reason for this was because it could probably be written in less than 100 lines of code in less than a day, so it was a quick win.

I described what I wanted to do. But I also pointed out the benefits for the vendor. Their competitors had this feature, or something similar, and thus were in a position to say they had basic functionality that someone else didn’t. From a marketing perspective, that’s not a good thing. I also pointed out how this would reduce support costs. A product manager could look at this and calculate how many support tickets it would take to pay for the development hours. They could then book in their ticketing system to see how many tickets of this type they were getting, and figure out how quickly the future would pay off.

If the math didn’t work, I wouldn’t have gotten my feature. So this is risky. But since I got a lot of these questions myself, and devised a workaround that worked for me but was too complicated for the person who was asking, I figured it was a safe bet that companies who didn’t have someone like me who had devised a workaround were going directly to them and blowing up their ticket counts.

The power of Good Enough

My solution wasn’t elegant or pretty. But I also figured that the more complex my request sounded, the less likely it would be implemented, and the more slowly it would be implemented. By asking for the minimum viable product, I was able to get a good enough feature much more quickly. Someone else can always ask them to pretty it up later.

The whole idea behind agile is to implement new features quickly. Sometimes a quick and dirty feature is good enough. And when it isn’t, you can make incremental improvements on it over time using the same model. This allows you to at least deliver something.

User story pitfalls

In my current position, sometimes I get asked to review user stories, some of them coming from the field. The way some of them are written, I sometimes have to guess at the intent. When that happens, there’s a chance I am going to guess wrong, and we are not going to implement what it was the requester wanted.

It reminds me of when I was in high school. They had some windows that were letting in too much light and causing unpleasant glare. Presumably there had been some trees or something there when the gym was built that weren’t there anymore. So they told their maintenance people to darken the windows by painting them. They painted the windows bright blue. The school colors were black and gold, and everything in the gym was one of those two colors. So those bright blue windows looked terrible. But nobody told them what color to use, so the gym had classy bright blue painted windows at least for the last two years I was there.

If they had asked them to paint the windows black, it probably still would have looked like a hack job, but at least it wouldn’t have called attention to itself. The more specific you are about what you want, the less likely you are to have a misunderstanding and get something that wasn’t what you wanted.

Tips for getting what you want

Software developers can’t read your mind, so it pays to be specific.

If you are writing the user story on behalf of someone else, ask questions to make sure you are understanding what it is they want and conveying it clearly.

If you are writing the user story on behalf of yourself, it can be helpful to have someone else read it over and make sure they understand what it is you are asking for. It’s reasonable to think if they can’t understand what you want, the developer reading it won’t understand either.

Being unclear is likely to lead to one of two undesirable outcomes. Maybe even both. One is that your user story will result in them building something that you didn’t want and doesn’t meet your needs. The other is that your user story goes to the end of the queue and stays there for a very long time as new requests that are more specific jump in front of it in line.