There are only two hard things in Computer Science: cache invalidation and naming things.
-- Phil Karlton

It's one of my favorite sayings about the craft of developing software. Phil Karlton said it in 1996 or 1997, and this is still very relevant. Nothing changed during the last twenty years. The biggest problems that you will encounter while building your app are communication problems, well, apart from cache invalidation of course. We, humans, are terrible at expressing ideas using written language. It’s quite easy to kill the project by using incorrect wording in the documentation.

Mike Cohn has a great example of miscommunication in his book “User stories applied.” A child of two or three years is going to have a bath. Child’s father has filled the bathtub with water and helps the child to get into it. The child dips a toe into the water and quickly removes it, asking to "make it warmer." After the father puts his hand into the water, he realizes that the water is much warmer than his daughter is used to.

Why is a child asking the father to make the water warmer if it needs to be cooled down? Because of miscommunication. To the child, “make it warmer” means “make the water closer to the temperature I call warm,” but for the father, it means “increase the temperature.”

Software requirements is a very fragile structure and can be easily destroyed by the misuse of a written language. That’s why most of the lengthy requirements specification documents fail miserably. By using user stories defined by an unambiguous and simple language you can minimize the risk of misunderstanding and make sure that the end product will be what you expect it to be.

What makes a user story

“It’s what I asked for, but it’s not what I want”
-- from Mike Cohn’s book “User stories applied.”

User stories represent functionality that will provide value to the users. It would be best if you changed the perspective from egoistic app-centric approach (e.g., “The app must be written in Javascript and have a real-time stream of updates” to and be user-centric (e.g., “As a user I need to be able to see messages sent to me ASAP to respond immediately”). A good user story is short enough to implement in one or two weeks and includes all pieces of the system. It should consist of the user role to understand the context and the end goal that user is trying to achieve.

Why do you need to write user stories

One of the most significant benefits of user stories is that everyone on the team understands them. They should be written in a simple language without domain-related or technical jargon. Stories are also great for planning because they are relatively easy to estimate if they are small enough. Of course, the estimation is rarely even close to the real amount of time things are going to take, but it allows you to know the relative complexity of stories.

What user stories are not

Two concepts are often get mixed up with user stories — user scenarios and use cases.

User stories are straightforward in nature — a one-sentence description of the user role, desired action and the desired outcome or reason behind the desire.

User scenarios have a much higher level of detail, describing the flow of user in the form of the narrative. User scenarios include additional information, such as the emotional state of the user.

Use cases are a completely different concept that comes from the traditional waterfall development practice. They are app-centric, focusing on functionality rather than the user. They describe how the system behaves and how it responds to user actions.

User stories are great to describe the app’s functionality for planning and estimating. Use cases are typically used by business analysts and are rarely useful in agile projects. User scenarios are great for UX practitioners but can be too detailed and time-consuming at the beginning of the project.

User roles

To write good user stories, you need to identify user roles. Based on your initial market research and customer interviews you can list types of users that will interact with your app.

Let’s say you want to build a coffee shop recommendation app. From the interviews in local coffee shops you’ve noticed that there are three types of people who would be interested in using the app:

  • Tourists, who want to find the best coffee shop nearby
  • Freelancers, who love coffee but also need good wifi
  • Coffee lovers, who are always on the look for a new coffee shop to try

Then you start thinking about the long-term life of the app and decide to add a few administrative roles:

  • Administrator who can manage the list of coffee shops and moderate reviews
  • Coffee shop owners who can post and update information about their business
  • Analyst, who needs access to various stats about the app

After you’ve defined what types of users you are going to have, you’ll need to add some details to understand the role better. How often is the user going to use the app? How well versed is the user with software? What are the user’s additional goals?

In the end, I would recommend adding the names and even pictures to user roles. That's the approach used by the UX professionals because it’s much easier to think what a real person would do than an abstract ‘role.’

Common mistakes:

  • Stories are too small. Look for stories that are similar and can be combined into one.
  • Stories are too big. A user story must be implemented within an iteration or it should be split.
  • Interdependent user stories. If you see that a user story can’t be implemented without the other one, then you need to rewrite your stories.
  • Overengineering. This one is usually connected to interdependent stories. Developers tend to find perfect solutions, but these solutions usually take an endless amount of time to implement. Make sure that you iterate by doing simple steps and trade perfectionism for robustness
  • User interface details in the story. You don’t know what the final design will be and adding the description of ‘pages’, ‘windows’ and ‘buttons’ to the story will confuse everyone in the future.

Writing user stories is hard, and it takes much time. However, when you finish the process, you will have a clear understanding of what you want to build, for whom and how the user will use your app. By writing user stories, you will also get a grasp of the amount of functionality you want to build. If your app includes too many stories, maybe you can cut down the functionality to implement only the most valuable features first.

What to read: