Using Wireframes in your Agile User Stories

· Posted by Leon in User Experience and tagged · 19 Comments

Hello, blog readers!

This is my first blog post for Balsamiq. Anyone who's worked with me knows that I have been a user and fan of Balsamiq since the beginning, so I am super excited to be a part of this awesome team.

Before coming to Balsamiq, I worked as a User Experience Designer and Business Analyst in Agile software development environments, so I thought I'd focus my first blog post on some tips I developed for creating Agile User Stories that served me well.

First off, I think that Agile and Wireframes go great together. Agile is fast, embraces change, and doesn't require precision. Just like Balsamiq!

In this post I'll explain my Story writing process by describing the steps I'd go through to create a User Story for a made up feature. These steps are: break up the design; order, prioritize, estimate; and write the recipe. I probably deviate a bit from the suggested formula and format for User Story writing, but I feel that it's still true to the principles of Agile.

Side Note: This post is written from the perspective of, and primarily for, someone who writes User Stories in an Agile Development environment. I'm thinking mostly of Product Managers, UX Designers, Business Analysts, and any other people who are primarily non-technical, but work closely with software developers who are the recipients of User Stories.


I'll start at the point that the wireframe is finished. At this point, a lot of the work is actually done, but it's important to take the next steps to craft a good User Story out of your design.

Let's say that you've come up with a design that allows users to view a list of customer demographic information. Something like this:

Now, it's tempting just to drop this into a User Story and say "build this." But it's important not to discount how much information is in your head about how this relatively simple page should function. There are some gaps that need to be filled in for the developer who's going to be building it. But don't under- or over-think these gaps. My Story writing approach is focused on "the art of maximizing the amount of work not done", which is one of the reasons I use Balsamiq.

This approach is all about taking advantage of the 80/20 rule.

The trick here is to combine the 20% effort that gets you 80% of the detail in a visual representation with the 20% effort that gets you 80% of the detail in a text specification.

There's no question that developers need detail in User Stories. Balsamiq is great because it will get you 80% of the information that you need to communicate with 20% of the effort of a more interactive or pixel-perfect tool. Now, don't spend 80% of your effort on that last 20% of the detail, just describe it using plain language in the User Story (I'll describe how later). The goal is not to have a huge, impressive-looking specification or prototype, the goal is to ship a product that allows your users to accomplish their goals.

Your User Story should be just enough to get it built successfully. Any effort beyond that is waste.

Step 1 - Break up the design

What often surprises product managers is how long it takes to develop user interfaces. A lot of that frustration is due to a lack of understanding about how user interfaces are actually built. There is rarely a correlation between how long it takes to design and how long it takes to build. That's why I like to take the time to divide up the design into smaller chunks.

Even this simple design can be broken down into pieces. Pieces, mind you, that can be delivered individually (as long as an order is obeyed). You can't deliver an incomplete feature, but you can deliver a small part of a larger feature. There's a difference. A button that doesn't do anything when you click it is incomplete. A data table that you can view but not edit, for example, can stand on its own.

Here's how I might break this feature up into pieces:

  1. The table and its content
  2. The search field
  3. The edit and delete functionality
  4. The ability to export

Note that, in that order, they can be delivered, and even released, in pieces. A table that doesn't have search may not be as useful as one that does, but it's still contributing towards the original feature requirement. Each Story should add some amount of value, however small, for the customer.

Side Note: Just because you're going to break up your work doesn't mean that you should think this way during the design phase. The value of Balsamiq is that it allows you to easily get what's in your head onto the page. And, more often than not, what's in your head is at a high level. So, go with it, and design what's in your head. Don't worry about the Story writing when you're designing.

Step 2 - Order, prioritize, estimate

A note about the ordering of the Stories. The important thing when breaking up a design into pieces is to find the foundation, the piece that other pieces will be built upon. In this case, I chose the table itself. You could argue that this is also the most important piece of functionality. The foundation often is. That's why I write this Story first. Writing the most important Stories first helps ensure that the most important features get delivered. With fixed release dates and shifting agendas, never assume that everything will get shipped. Start with the important stuff and you'll at least be maximizing the value of your time.

When I insert the wireframe into the User Story (as an embedded image, attachment, etc.) I don't necessarily remove the peripheral information once I've decided how to break the design into its components. One of the things I like to do is show the full wireframe that I created, but obscure the parts that don't apply to the specific Story. That way, it's clear what the objective of the Story is, but you're also keeping in focus the end goal.

I might do something like this, for example:

I've greyed-out the peripheral pieces, yet left them visible for everyone on the team to see where we're headed. The numbers refer to the Story numbers of the other pieces.

One real benefit of breaking up the design like this is that now you can get estimates on each of the pieces (and the wireframes alone should be enough to get estimates), which should not only be more accurate, but can be divided up across sprints. Let's say that after the estimation meeting the point values end up something like this:

  1. Table with customer data - 2 points
  2. Edit and delete functionality - 4 points
  3. Search - 1 point
  4. Export - 3 points

This will allow the product owner to make better cost-benefit decisions about the overall set of features. Maybe the export function is something that one noisy customer keeps asking for but that you know won't be used by most of your customers. Seeing that this piece is relatively more "expensive" than some of the other pieces might prompt you to put it off until the next release. This wouldn't have been possible if all you had was a 10 point estimate for the whole design.

We've actually come a long way already at this point. But don't stop there, there's one more step!

Step 3 - Write the "recipe"

The final phase is to use the wireframe to help you figure out the details that the developers need to know to build it. A trick I learned to do this is to imagine yourself using it. Balsamiq is awesome because it clarifies the picture in your head of what you're building and allows you to picture its use. I've found this process to be extremely helpful in providing the details that the developers want while building it.

Creating a wireframe is kind of like cooking something. Think about cooking your favorite dish. Now, think about writing a recipe for how to cook what you've made. It's a different process entirely. It's shifted from creating to communicating. It's all about putting yourself in their shoes and not making too many assumptions about their level of understanding or knowledge.

The lesson here is that the process of creating the wireframe is actually more for you than for the developer. It helps you figure out what you want to build, which, in turn, makes it easier to communicate how to build it (even if you're completely non-technical).

The structure of a User Story that I was taught is the following:

  1. Summary/Story Narrative
  2. Wireframe
  3. Acceptance Criteria

Side Note: I like to include the "why" of what we're building in the Story Narrative section and explain what value this feature provides. Believe it or not, developers care about this. And this explanation should pass their "smell test" too. If you can't get them to "buy it", maybe you should revisit why you're doing it.

The third part is Acceptance Criteria (also called Conditions of Satisfaction, Acceptance Tests, etc.). This section is both for the developers and the testers. Here is where I think I take a bit of liberty with the traditional format. I like to think of this section as the recipe part. Here is where you, to the best of your ability, tell the developers how to bulid it. Don't worry if you have a hard time with this at first, one of the benefits of this process is that it helps you learn what information developers need to build things. It opens the window into the development process, which benefits everyone.

Again, here we start with a foundation. Don't be afraid to get very basic. I might start, for example, with "Create a table with the following columns: Last Name, First Name, Address, Phone". Small pieces make it easy to check things off, and often actually correspond to the chunks of code the developer has to write.

Now that you can see this table with customer information in it, picture using it. Aside from the features that you've deliberately split off into other Stories, what might you, as a user, see and do here? Can you sort columns? If so, all columns, or just some of them? Anything that you can come up with along these lines is most likely information that the developer needs to know.

As a bonus, if you're somewhat technically savvy, you might be able to think of other things the developer might want to know. You might know that address data is stored in separate database fields (street, city, state, zip, for example). If you don't specify, the developer may create separate columns in the table for each of these, because that's how they see "address". But, you may know that users prefer to see these fields together (maybe so they can easily copy and paste them all at once). So, add to your recipe that the address field should include street, city, state and zip together. Trust me, stuff like this is important.

But, also, realize then that users probably won't be able to sort the table by city, for example, because "city" is not a distinct column in the table. Product managers often want it both ways. Being forced to write the recipe yourself doesn't allow for that. It's a trade-off: do you want a more human-readable address field, or do you want to be able to sort by each part of the address? It's up to you. This is not the developer's problem.

For this particular Story, here's what my acceptance criteria might look like, just to give an idea of some other possible details I might include.

Acceptance Criteria

1. Create a table with the following columns: Last Name, First Name, Address, Phone 2. Add a level 3 heading title above the table with the label "Customers" 3. The Last Name, First Name, and Phone columns should include the last name, first name, and primary phone number fields, respectively, for each customer 4. The Address column should be comprised of the following fields (in this order): street, city, state (abbreviated), and zip code (5 digits only). Wrap the text to the next line at 100 characters. 4. By default, order the table by customer last name (ascending) 5. Allow the table to be sorted by last name or first name 6. Add pagination at 25 rows

See how many details there can be for a simple 4-column table?! The take-away here is not about how hard it is to build this table (it may take only 30 minutes if you already have a table framework in place), but how many decisions need to be made when building it. And that, if you don't specify them, those decisions will either be made by the developer or the framework you're using. As in many cases, not making a decision is making a decision. Now, if you don't care, that's another thing. But I would argue, as would many others, that details matter.

At this point, I would show the Story to the development team for a reality check, make any modifications necessary based on their feedback, and put it in the development queue. That's it! Then, on to the next Story… 😉

A few final tips:

  1. Sometimes you'll want to make minor tweaks to the Story after the wireframe is done (label changes, etc.). Even though updating the wireframe is easy, sometimes I'll just update the text of the Story. I make it known that if there's a discrepancy between the text and the wireframe, always follow what the text says.
  2. Be casual in your language. Write like you would write for someone who's looking after your dog while you're away. Don't be afraid to write thing like "the styling should look like our other tables" or "work with the graphic designer to create an export icon". Only include as much detail as necessary. Ask the developer if anything is unclear to them.
  3. Every developer is different, so you may end up changing the level of detail based on your team. Some just look at the wireframe, some go straight for the acceptance criteria. Some improvise when details are missing, others refuse to continue until they get clarification. Try to learn their styles and preferences. Ultimately, try to take responsibility for making your Story clear and easy to understand.

This process has been successful for me. What's your Story writing process? What tips have you developed for writing User Stories? If you have any thoughts on the process I've described or your own tips for writing User Stories, feel free to share in the comments.

Get the Inside Scoop

We'll send you just one email a month and share a ton of information that you'll get before everyone else. More info about the newsletter here.

We'll never share your email address or spam you.

Leave a Comment

Your email is never published nor shared.

Comments (19)

  1. Great write-up! Thanks, Leon. This post is very practical; I want to share it with every BA I know. I am also a big fan of balsamiq, and a former BA.

    I agree that lo-fi mockups are the best way to communicate product requirement. It helps clarity but not over polished, which leaves room to encourage communication. I always use balsamiq mockups if the team is distributed. For co-located team, I like do whiteboard session with devs, draw the mockup on board and attach the photo to my user stories.

    P.S. I came across this blog because I was doing research about mingle. Thanks for mentioning that. Mingle has added checklist support. You can also check off tasks as you go in Mingle now 🙂

  2. Nice article Leon! I’m currently part of a Scrum team and i’m trying to find ways on how we can work with the BA to create useful mock-ups without going overboard together with our user stories. We seem to have discussion about how many variations of the mock-ups do we need… Hopefully we will come to an agreement and move forward in the right direction.

  3. Hi Lion. Thanks for the article. Very useful. But I have a question:

    If I got it right, you come up with the wireframe before writing the first story, in this case the epic “Customers”. Is that right?

    I thought it was more appropriate to use wireframes to support acceptance criterias but only aftter you have made clear the business need first.

    Here I understand that you are designing the page first, saying how it should display the UI elements before writing a single story.

    Am I wrong?

    • Hi Thiago,
      Thanks for the comment and good question.

      I use wireframes in at least 2 different phases. The first is when I reflect back to the PM what I’m hearing from them about the business needs. This is usually at the epic level or larger. It allows them to validate the design before approving it. Then, once the design has been signed off on, I use the same wireframes and split them up into smaller pieces to create stories from to support the acceptance criteria.

      To summarize: there is a conversation that happens before what I wrote about above that I didn’t really get into. So, at this point the business needs discussion has already happened and the UI has been iterated over (at a high level, at least).

      Hope that helps,
      – Leon

  4. Enjoyed your article, Leon. Thanks!

    You must have a favorite tool or two for writing and prioritizing your Agile user stories…and that work really well with Balsamiq Mockups of course.

    I’d appreciate any recommendations you can send my way. Thanks.

    • Hi Denny,
      I really liked Mingle because it allows you to insert images (e.g., mockups) inline with the text of the user story. Pivotal is another tool I’ve used. It doesn’t show images as nicely, but I like that you can check off tasks you’ve added as acceptance criteria as you go.

  5. Thank you very much for such a wonderful article

  6. This article was in my Pocket for days and I could read it now. I’d like to say it was worth reading it! This is a simple and user centric approach. You got points related do “Lean” and agile practices, really bringing value to each story. As a developer I must say most product owners can’t be so plain on what they want, as you demonstrated here. Thank you!

  7. Hi Peter,
    Sure thing.

    I’m just making this up, so I’m imagining some more details about this fake story. Let’s say the story title is “Technical Support would like the ability to view basic customer data”

    The summary / story narrative portion could read:

    “Many technical support issues are caused by incorrect data in the customer database. One way to help the technical support staff would be to allow them to easily view basic customer data so that they can verify its accuracy when they are on the phone with customers. This story lays the foundation for this work by creating a read-only table for the Admin screen. Future stories will enhance this functionality with the ability to search (see #1234) and edit (#1235) the data.”

    You could think of it as an “elevator pitch” for the work the story is proposing.

  8. Good article. Could you provide an example of your “summary / story narrative?” I.e. something similar to the example given for Acceptance Criteria.

  9. I think the 80/20 rule applies across the board in software development generally. Its amazing how you can get 80% of the job done in 20% of the time, Equally I find that 20% of the problems take 80% of the time to resolve.

  10. I’ve worked along these lines for a while but lately I have also learned how to write feature files for Cucumber testing.

    They (or any similar framework) add some structure when writing criteria or describing actions that are hard to show in a mockup, but more importantly they also force you to think about edge cases or different starting situations, those that usually come up when developer has come about half way.

    Here is a blog post with some examples,

    Björn Simonson (@b_simonson)
  11. Pingback: My “Agile” experience | TsoDa Place

  12. Nice article, Leon. Getting the right amount of detail in a story is truly an art form. The effort is most appreciated… even if it means looking after your dog 🙂

  13. Toby, thanks for the feedback. I don’t think you should need to include more back-end perspective in the user stories since that shouldn’t factor into the acceptance testing. Sometimes, however, you need some bigger back-end tasks to happen first. I think it’s ok to create “chore”/”task” or “spike” stories separately to do back-end work that’s necessary to support front-end updates. Regarding the “as a…” format, I usually do write that in the beginning of the story (in the Summary or Story Narrative). I think it’s sufficient to capture the user’s perspective just in this section.

  14. As a developer and an avid user of the Balsamiq Product , I take a similar approach with a healthy dose of “functional requirements” sprinkled throughout. This approach allows me to have meaningful iterative deliverables.

  15. Nice article! I especially appreciate that you noted developers want to connect with the feature, and how important their sniff test is for validating why the story matters. Nicely done.

  16. Really nice article – really enjoyed that. As a product owner, it is sometimes get the balance right with what the actually need developers need and what they claim they need, like big functional specifications. Just wondering if you think the user stories in the product backlog need refining beyond the UI requirements and delve more into the technical back-end functionality in order to get developer ‘buy in’? Also, I was wondering why you didn’t use the format of ‘As a…I want a…so that..’ to frame the user stories?

  17. Totally agree in your idea of how details matters and its so true stories you are pinpointing. Great text, thx!