en | ru

#8. All about user stories

In this article, we'll have a look at exactly how Stories are written, including the optimum level of detail and what issues to consider when compiling them.

As mentioned in a separate article, a Story accommodates the requirements for the component under development.

Ideally, the Story is compiled by the Product Owner (PO), however, in some cases, it's not a good idea to delegate this task to one person, since he may not have the necessary competence (for example, the Story might require a description of the mechanism of plastic card transactions processing systems, and the PO is not an expert on banking sector technicalities). Also, an individual working on his own might make a mistake (e.g. at the end of a long working day), and the error can slip unnoticed into Backlog and lead to incorrect implementation of the function. For these reasons, it's good if two or more people collaborate when writing a Story: a Business Analyst (rarely), a Product Manager or a Project Manager (PM), in addition to the PO.

User Story; Inventing

It's called "User Story" because, in most cases, it's written with the hypothetical user in the first person, describing the functionality that he would like to see.

Usually, stories are made based on a finished design, or, in rare cases, based on a prototype, with the assurance that the design is not subject to further change, because rewriting a Story is risky.

So, let's suppose we are a team. I am a new Product Owner, and you are an experienced Business Analyst with whom I'm consulting.

Suppose our client is the owner of the "JPUB" online platform, which does digital publishing. Our client's users create their digital journals on it. Our role is to provide technical support for this platform and to develop functions at the client's request.

One day I receive the following request from our client:

"I want our publishers to be able to limit access to their magazines for different countries. We need this feature the day after tomorrow."

Deadlines are terrible. It's a pain in the neck to have to respond to tight deadlines, but sometimes that's the nature of the job – c'est la vie…

On the other hand, this particular request doesn't look too complicated; we simply need to add an option where publishers will be able to specify the countries from which you are permitted to get access to the publications ... I need to run to the designer, so I'll ask you to quickly sketch something first:



Okay, now we have a design sketch where publishers can activate access restrictions by country and specify the countries that are permitted access. I come to you and ask for an opinion. You are puzzled by my sketch and ask, "Why not add the ability to block individual countries?" After all, if we are talking about restricting access, then it's obvious that publishers will find it easier to limit access for several countries rather than have to permit access for several hundred – your solution is stupid!" Hmm, you're right, it seems I was day-dreaming about how much I love Greece! So I give it a thought, and add to the sketch the option to block:


I return to you with the updated version, and explain that now the publisher will be able to select one of two items: Allow, for permission or Deny, for blocking, and that only one of the lists can be active at a time. You look at me sadly again and ask the question, "Can we really guarantee that none of these countries will have access?" And I have to admit: "Well, I guess not. After all, we use the IP address to determine the visitor's location and to restrict access. So if someone is using a VPN, or some other technology to hide the IP address, then obviously he will still be able to get access." You respond very reasonably: "then, in that case, shouldn't we explain the limitations of this function to the publisher? Otherwise, they might complain that a visitor was able to access their publication, even though they were on the list of blocked countries."

Chastened, I return to my sketch and add the appropriate caption under the option:


Afraid that I'm beginning to look like a complete idiot, I decide to think a bit more, and remember the license agreement which governs the JPUB project: it clearly states that a user who has bought access to an online magazine is entitled to have unlimited access to it. So I realize that if we implement this restriction function as I have drafted it above, what will happen? – many readers who have bought online magazines will suddenly discover that they are in a restricted country and will lose access to the items that they purchased. Oops, that could have been another embarrassment! So I add one more line to my layout:


And I come back to you. I explain in detail my deliberations and the smart work I did. You duly praise me: "Well done, looks like it's sorted now," but on your way out of the office you add in passing: "by the way, it might be an idea to add a description of the items "Allow" and "Deny," just in case anybody muddles them up. After all, our client has millions of users around the world, and their English might not be brilliant..."

I thank you for the tip and run to the designer, asking him to add the last couple of details. The designer duly modifies it following my wishes, and says goodbye, leaving me in the office alone.


So, now I have a design, and I know that pretty well, the only thing I could change is the color; in terms of functionality, I would like to imagine that everything is in order now. I sit down at my workplace, launch our corporate project management tool (Trello, JIRA, Asana, Basecamp, whatever). In the Product Backlog, at the very bottom, I create a new Story.

I'm going to set out the Story as if I actually wrote it. Quotations from the Story will begin and end with two slashes "//."

Let's call the Story "Restricted access by countries" and move on to the content.

If I were a publisher of the JPUB platform, on the page where I manage my journals, I would like to see a globe icon, and if I click on it, there will be options to restrict access by country.

// as an option, you can point to the location of the icon with an arrow:


Or, you can follow team practice, which is to use numbers, as in the attached image, and to refer to them in Story, for example:

"I would like to see the icon of a globe (1), with ...." with an attached image:


And so on. There are countless options; the main thing is to agree with your approach in advance with the Team that will work with these Stories. Let's continue.//


In the window that opens, I want to see a switch that will allow me to enable/disable the restriction option by country.

I want to see the "Allow" and "Disable" buttons, with question marks next to them, so that when I hover over them, the corresponding hints should appear:

(For "Allow"): Publication will be available only in specified countries

(For "Disable"): Publication will not be available in specified countries

When I activate the "Country Privacy Settings," then "Allow" button should be selected by default.

Under the buttons, I want to see an empty field where I can enter the names of countries.

As soon as I click on the input field, I want the system to tell me that I must enter at least two characters to get a list of available countries.


I want to be able to add an unlimited number of countries to any of the lists, and remove them from the list by clicking on the "X" in the country name, or via the Backspace key with the selected input field.


If I select the "Allow" button and enter the names of countries, I want the system to allow access to my publication only for those users whose IP address belongs to the country/countries I have listed.

If I select the "Disable" button and enter the names of countries, I want the system to prohibit access to my publication for those users whose IP address is from the country/countries I have listed.

I want the lists of countries that I have compiled to be saved under the buttons so that when switching between the "Allow/Disable" buttons, the lists are not erased, and I can continue to edit them.

Under the input field, I want to see two system prompts:

  • *We use the visitor's IP address to determine the country.
  • Users can still access this publication if at the time of purchase the country was authorized, or if they received a special offer by mail.

As soon as I enter the desired countries, I want to be able to save the settings via the "Save Settings" button, or, if I change my mind, close the window by clicking on the "Cancel" button.

That's it!

Now, when the designer comes to work in the morning, s/he can attach design files to our Story, and it will be ready for development. We wrapped up our Story rather quickly and happily ran home to sleep. In the morning, when planning the day's work, the Team, as per our client's wishes, will develop the Story in a particular order, and everything will work out fine – or so it seems. Let's just double-check to see if we really have ironed out all the bugs in our Story.

Well, we did quite a good job of describing how it works. We very meticulously described the buttons, texts, switches, we even considered nuances such as what happens when switching between lists, and we specified the minimum number of characters required for input to prompt the system to give us a list of countries. At first glance, everything is in order. And yes, developers can, without having to check the details, start developing a story, and testers can examine the Story and create test cases.

BUT… there is one problem that we forgot: we didn't specify what will happen if the user follows the link in the browser to a magazine that is restricted in his country. We completely forgot, and we can only hazard a guess at what will happen if the Story is implemented exactly as we designed it. Very probably, an ugly page will pop up on the user's screen: at best it will show a system error - it might just be a blank page with some short line of system error in the upper left corner, such as:


If the project was simply a personal blog, then maybe this mistake would be somehow forgivable, but our client, JPUB, is a huge online platform with millions of users. In fact, as soon as a handful of platform publishers start using this function, several thousand, or even tens of thousands of users who try to access their favorite magazine will instead be disappointed to see an unresponsive page, and this – have no doubt about it – will badly affect the project's reputation (the JPUB platform will get the blame, not the publishers).

And so, we have to rush off to the designer again and beg him to drop everything and quickly create designs for the missing access restriction page. This is attached to the Story, and then we run to the developer and heartily apologize to them for having forgotten about the page, and so on. Drama! Grief! But finally, the page is ready.


You see now how such a seemingly small Story became a big headache due to the carelessness of the Product Owner.

And the purpose of all this was? Well, I showed (in some places, exaggerated) the process of compiling the Story, with the aim of helping us to have a better understanding of the following rules:

  • The correct format of the Story is the one that is agreed with the Team. It can be a first-person narration, it can be a "text - picture" format, it can be anything: the only rule is that it has to suit the whole Team that is going to work with the Story;
  • The correct detailing of the Story is one that is coordinated with the Team. The level of detail of the Story decreases in proportion to the length that the Team has been working on the project because many things become obvious with time. Conversely, if the Team is new, there should be more detail, in order to avoid misunderstandings;
  • The correct size of the Story is one that gives enough information to all team members working with the Story so that there are no unanswered questions.

Composition of User Stories 

The art of writing Stories is to determine the minimum amount of information, which will be sufficient for the Team to develop exactly what is needed.

To do this, the Product Owner has a number of tools that he can safely use in Story (provided he coordinates with the Team, of course):

  • Screenshots
  • Screenshots with notes (like the ones we have already seen in this article)
  • Screencasts (video)
  • Sketches, Layouts and Design files
  • Presentation files (rarely)

In other words, pretty well anything.

The Product Owner should not limit himself to a "single style" when compiling Stories, because that wouldn't be flexible enough. If a team needs screenshots, then the PO makes them. If a team needs videos, or sketches draped on stickers, then the PO creates them.

You shouldn't sneer at anything, even this:


Notes for the Product Owner

  • If you want to do the job quickly, don't rush;
  • If you're planning to stay in the office until late, to finish something so that it is ready in the morning for the rest of the Team, forget it, such plans rarely work. At the least, you should be prepared to check for urgent messages first thing in the morning;
  • If you have already had to change the Story twice, and you're still not satisfied with it, then have a cup of tea, take a walk in the fresh air, return to the workplace, and go through it one more time;
  • If you're checking the Story and you skip a few paragraphs "because everything is clear there, I've read it a hundred times," then have a cup of tea, take a walk in the fresh air, come back, and read those paragraphs again;
  • If you find yourself quietly smiling as you read these notes, and the word "familiar" occurs to you, then you're doing great.

We've come to the end of this article, and I want to show you how the above "Story" was compiled by me in the PRD (Product Requirements Documentation) format in Joomag:


So, now we know all about Stories: how they are vital elements in the project development process, how they are composed, and what they look like.

In the next article, we will look at the technical component of the project; that's to say: we will go through those technical elements that the manager will not interfere with knowing for more competent work.