What is a User Story?

If you are looking to start a venture that has to do with software (i.e. building a mobile app, website, etc.), then learning what a user story is will be one of the most important foundations that you must learn...so listen up! A user story is going to be your north star, it is the most efficient tool for explaining what you want your application to do. The beauty here is that with a user story, it doesn't matter if you're technical or not. ANYONE can write and understand a user story.

A classroom with a blackboard

Essentially, if you aren't the one who is doing all of the coding, then you need to be sure that you write up a user story to clearly articulate what you want your team to build. So, when you need to communicate your vision to your developer, you do it with a user story.

I know someone reading this is going to ignore this article and try to just explain things instead of taking the time to write out a user story. I KNOW it will happen, and when it does, you will lead yourself to a journey of hurdles as you have to reiterate things and redo builds as they aren't to your liking. Take the time and learn how to write a user story, it is absolutely critical to the success of your development experience.

How to Write a User Story

There are five components to a user story: User Type, Module, Feature, Action, Sub-Actions. Each component offers its own purpose and value, so it is important to be sure you aren't skipping any steps, or determining for yourself which component actually matters.

A user story is written in the following format, almost as a flow:

User Story
  • Module
    • Feature
      • Action
        • Sub-Action(s)

We'll break down each component for you, below.

User Type

The user type is very important, as that basically is going to outline what user flow you are referring to. There can be many different types. Let's imagine a marketplace as an example. In a marketplace, you have the users that are buyers and the users that are sellers.

Shopping cart for a brown coat

The flow, features, actions, etc. for a buyer is going to be different than a seller, right? Furthermore, there will be an administrator who can oversee the marketplace itself, and the flow of this admin would be different than both the buyer and seller. So, it is important that we define whose user story we are writing, and write one for each user type.


A module is reflective of one of the main components of the application; think of this as one of your core pillars. If we look to a marketplace again as an example, some of the modules that come to mind would be the marketplace itself, or the login, or maybe product management. Within each of the modules, you will have a handful of features.

Think big. The module is what houses all of the features that are related to the same pillar. So, within each module, you are going to have a list of features, as well as a plethora of actions related to each feature.


A feature is going to be, you guessed it, a feature! Features are reflective of individual components themselves, rather than the sum of all components. So, taking back to our marketplace example, a feature for a buyer user type within the marketplace module would be the listing of available items, or the ability to add an item to your cart.

A phone scanning a QR code on another phone

Some modules may have tons of features, while other modules have very few. That is okay! There is no "right" answer here, and if you end up making a feature a module itself that has other features within it, rather than listing all features under a single module, again, that is okay. As long as someone can clearly follow your flow, that is what matters.

A feature can be a simple title, or it can be a description of a module. The key here is to remember that there is no specific right answer, each user story is dependent on the project itself.


An action is the actual interaction a user has with a specific feature. So, under the feature described as the market place listing, an action would be scrolling through the listing itself. Another action could be interacting with any of the items in the listing. Maybe if you click a drop-down you can see more text describing the item, or maybe if you hover over the item it enlarges like a magnifying glass. At the end of the day, you can think of the action as the actual actions a user is taking.

So, in summary, every single feature should have actions! If it doesn't have any actions, then that means the user has zero interaction with it, which means it isn't a feature :)

Also, an action can be a simple title, or it can be a description of a feature. The key here is to remember that there is no specific right answer, each user story is dependent on the project itself.


A sub-action is simply an action with an action. For example, maybe on this listing, you can heart an item to move it into your favorites.

The hearting of the item would be reflective of an action. However, what if you wanted to un-heart the item? Well, you can only un-heart an item if you have already hearted it. So, the sub-action under hearting an item would be the user un-hearting the item. We're getting a little meta here, but hang in, we're almost done.

Let's See It In Action

We are going to use Instagram as an example here to write an example of a user story.

An image of Instagram login
  • Main Feed (module)
    • Listing - a user sees a feed of images uploaded by individuals the User is following (feature)
      • Like (action)
        • A user double taps the image or selects the heart. After doing so, the heart will turn red and the number of likes will increase by one. (sub-action)
      • Comment
        • A user can comment on the post and submit the comment.
          • User can cancel the comment to go back. (sub-sub-action)
        • A user can like someone else's comment by clicking the red heart outline.
      • Profile Link
        • A user can click the name of the person who posted to be redirected to their Profile
      • Location Link
        • A user can click the location, just under the users name, and be redirected to the Explore feature that will show all other pictures using the same location.
    • User can see the Stories available to view from their Following.
      • View
      • Post a Story
        • Click your Circle in the top left of the screen
        • Swipe your screen right to be taken to left one screen to take a picture
  • Profile
    • User bio
    • Favorited Stories
    • Posts
  • Explore
    • Search
    • Explore Categories (the options above the images but below the search bar)
      • Shop
      • Decor
      • Travel

You get the idea.

Remember, this is NOT an easy process. It takes a lot of time and A LOT of iteration to get this right. While you may be banging your head against the wall, it is a necessary pain. Give it a shot, have some review it. Ask questions and see where (if) they got lost, or if anything wasn't descriptive enough. If there is a question that isn't answered, then you don't have a complete user story.

Now it doesn't need to be perfect, but it needs to be in a spot that you are fully satisfied with, because any lack of clarity in the user story will come back to bite you, I can promise you that. So, just in case, always over communicate and make sure that whoever is developing truly understands what you are looking to do; you should not rely on them just reading the user story, it serves purely as a reference. We have more on user stories here.

Want us to take a look at your user story and see if you'd be a good fit for Aloa? Feel free to shoot us a note at resources@aloa.co or fill out a form on our website!

The views expressed in this post are the writer's and do not necessarily reflect the views of Aloa or AloaLabs, LLC.
See why 300+ startups & enterprises trust Aloa with their software outsourcing.
Let's chatLet's chat

Ready to learn more? 
Hire software developers today.

Running a business is hard,
Software development shouldn't be ✌️