Using Balsamiq Mockups with Pattern Libraries and Frameworks

People often wonder how much visual detail to put into their wireframes. There's an attractive elegance to a simple black and white sketch, but it can sometimes lead to gaps in the shared understanding of what the final product will really look like.

Wireframes shine during the early phases of product development when ideation and rapid iteration are most valued. But what makes them ideal for this phase also hinders them in the next phase, when pixel precision and visual details are called upon for implementation. Despite this, many people (I'm guilty of this as well) try to incorporate these fine-grained and aesthetic details into the wireframe itself by tuning fonts and adding colors and other visual effects.

This can often lead to confusion when these high-fidelity wireframes are used as implementation specifications and sent "over the wall" to the development team. Most wireframing tools are not optimized for creating artifacts that look and feel like a finished product. Yet creating polished renditions of every screen using a tool like Photoshop is time consuming and may not translate well to the final product anyway.

There is another way. The only requirement is good communication within the team.

Separation of Concerns

An alternative to pushing wireframes beyond their limits is to keep them low fidelity and let another tool do the work of specifying the look and feel. Tools for this purpose are already well established, in fact, especially for web applications and sites. Sketchy, (mostly) black and white wireframes pair very nicely with pattern libraries (and, to a lesser extent, style guides). Before diving in, let's define what they are.

Sketchy, black and white wireframes pair nicely with pattern libraries.

Like their younger sibling, style guides, pattern libraries contain definitions for a particular look and feel. They go one step farther though, in that they often define behavior and are backed by working code. Large companies have been using pattern libraries for a long time but until recently they were too labor intensive for smaller companies, often requiring dedicated designers and developers working outside of the primary product teams.

This changed when the Twitter Bootstrap (now just called Bootstrap) framework was released a few years ago. It was (and is) a free starter kit for web development that provides compliant, robust HTML templates and generally good-looking CSS styles (which can be customized to suit your brand). It comes with its own grid and typography definitions as well as styles for buttons and forms. In short, it takes a lot of the hard work out of starting a web project and making sure that it will work across browsers. A framework like Bootstrap can be used as a good foundation for a pattern library.

Pattern Libraries + Mockups in Practice

The main advantage of pairing a pattern library with Balsamiq Mockups is that it can free you from worrying about look, feel, and behavior when designing yet provide pixel-perfect renditions of the final product components.

If you already know what a button (or tab, menu, etc.) is going to look like and what its state transitions will be when you click it, you don't have to style it in your wireframe. Black and white and Balsamiq Sans is just fine. Having a pattern library can allow you to jump straight from wireframes to code without leaving the final vision undefined.

Having a pattern library can allow you to jump straight from wireframes to code without leaving the final vision undefined.

Here's how you can introduce them to Balsamiq Mockups. You'll find that they get along quite well together!

If you have the resources you can create your own pattern library or you can start with a customized download of Bootstrap or Foundation (more examples at the end of this post). The next step is to create a mapping between it and the controls in Balsamiq Mockups. This essentially amounts to developing a shared agreement of "(this) means (this)." You can do this by creating a document showing these mappings or by having a meeting with the design and development teams around a screen to work it out.

Here's an example of how you might map some Balsamiq Mockups controls to Bootstrap components (you could also start with our Bootstrap Mockups To Go library).

Mockups and Bootstrap

(Note: It's ok to use some color, but it should only be used as much as necessary to indicate states and selections, for example.)

Having this kind of mapping means that developers no longer have to wonder whether the colors in the wireframe are supposed to be used in their code. They can just translate in their head that a blue button in the wireframe actually means a green button in the UI (if that's the color you use) and that breadcrumbs separated by the '>' character should actually be separated by the '/' character in the app, for example.

Having this kind of mapping means that developers no longer have to wonder whether the colors in the wireframe are supposed to be used in their code.

You can also extend your pattern library by creating your own Balsamiq Mockups controls as Symbols to map to other components in your library.

Mockups and Bootstrap

This mapping can evolve and grow over time as needs and design language change in your organization.

Here's a simple example showing what a completed wireframe could end up looking like when built using a pattern library (note that blue in the wireframe doesn't have to mean blue in the finished product).

Mockups Email

Bootstrap Email

Wireframe to working code with no additional design artifacts in between!

Having a pattern library also means that you're reusing the same code across all parts of your application so that different developers produce the same UIs, which leads to better standards and consistency. And designers can rely more on the stock controls rather than spending hours trying to replicate the look of their own, so both the design and development cycles are shortened.

Summary / YMMV

This approach won't work for all projects or organizations.

It is better suited to in-house teams, for example. Clients outside your organization are more likely to want to see a high-fidelity mockup or comp. Also, many of the existing pattern libraries are for web-based products. Desktop and mobile application pattern library templates and examples are less abundant. Additionally, you should have good communication between design and development teams for this approach to work. Waterfall and remote teams might struggle with this.

That said, it does offer many advantages in certain setups, such as:

  • Saves time when wireframing
  • No mismatch between mockup and reality
  • Good for Lean/Agile methodologies where deliverables don't need to be so formal
  • Good for small teams and startups without many resources (especially when using frameworks)
  • Different skillsets can be applied to different design areas (e.g., visual designers and developers for the pattern library, interaction designers for the wireframes)
  • Design processes (wireframes vs. pattern library creation) can be done independently resulting in fewer bottlenecks
  • More UI consistency across the product

Pattern Library Examples and Variants

Some resources to help you develop your own pattern library:

What do you think? Have you had luck using wireframes in conjunction with pattern libraries? Feel free to leave a comment below!

Dan Olsen on Becoming a Lean Product Ninja

Dan OlsenDan Olsen has traveled the country teaching people how to become "Product Ninjas" by introducing Lean product development processes into their organizations. He also consults with startups on how to create better products and processes. I was fortunate enough to get some time with him recently to discuss his insights and what he's excited about right now.

Dan's recipe for building great products

We started out by going through some of the concepts he covers in his presentation "Building Great Products the Lean Startup Way," which you can watch below. (You can also see a similar version without audio here.)

Product-market fit

When talking about his presentation, Dan started off by summing it up this way: "my talks are about distinguishing problem space vs. solution space and achieving product-market fit."

He says that determining what problem to solve is key and that the problem is conditional on identifying a target customer. You need to have someone who not only has that problem but is willing to pay you to help them solve it.

"You put your product out there, it's like bait on a hook. It's going to attract a certain kind of fish."

He likens product strategies to fishing. He says, "you put your product out there, it's like bait on a hook. It's going to attract a certain kind of fish." In one model, you may have bait that you know attracts the type of fish you've determined that you're going after, but "sometimes you throw your hook in the water without a good sense of what you're fishing for." In this case you end up with whatever fish responds to the kind of bait you have.

This latter model is growing in popularity with the greater availability of data and analytics that allow you to more easily discover who's buying your products, and the rise of concepts like Lean and Agile, where iteration cycles can be shorter and product teams can respond more quickly to feedback.

He cautions that just because you may have a lot of data about your customers doesn't mean that you really know them. You can get all kinds of demographics on gender, location, age, etc., but it can be hard for this data to be actionable. He thinks that talking to customers (the "fish" you've caught) directly can be greatly valuable. What works in practice, he says, is "you see what you catch and you talk to them... and you discover what they have in common." This helps you begin to learn which people value the benefits that your product provides relative to the other products out there.

He describes this as a kind of circular logic, yet it works. You put your product out there with a specific problem in mind that you're solving. Then you see who buys it and you iterate on your product by learning more about the problems those customers face, which may or may not be in the problem set you initially set out to solve.

Now that you've learned more about which customers are interested in buying your product, you can stop targeting the ones who aren't.

A consequence of this is that some attributes of the customer demographic that you had in mind initially will inevitably "fall out", meaning that they're no longer primary audience attributes for your product and shouldn't be targeted going forward. This completes the cycle; now that you've learned more about which customers are interested in buying your product, you can stop targeting the ones who aren't.

Making the leap to solution space

Once you've established a clearer idea of your target audience and their problem space, it's time to focus on the solution space, which is where design and wireframing come into play. Dan says, "design is the creative leap from problem space to solution space."

A lot has changed in this world as well. When consulting with or talking to Product Managers he will start by talking about the traditional role of a PM, saying that the old model was that a PM would write a large Product Requirements Document (PRD) and then hand it off to the development team. He says that PMs used to get by "living in [Microsoft] Word" but that's no longer the case.

Many companies are going Agile, writing user stories, and following the Lean Startup methodology. Yet that alone doesn't lead to better solutions. "When you have dozens of user stories it's hard to get a sense of what the heck is going on."

He says that wireframes and a UX presence in the organization help "tie it all together."

"You give developers text, what do you expect to get? You're going to get whatever UI they come up with. And that's not their fault."

When talking to PMs his advice is to hire a UX designer if they haven't already and to start including wireframing in the design process. In the old model of PRDs and similar documents, "you give developers text, what do you expect to get? You're going to get whatever UI they come up with. And that's not their fault."

In place of the PRD in modern organizations he says that now "the combination of annotated wireframes or mockups plus the user stories become the spec."

Dan's model of a "fully staffed product team" includes PM, UX design (specializing in information architecture and interaction design), visual design, and development (front end and back end). He says, "that's the continuum of skills you need" and, ideally, each role knows a little bit about the adjacent ones to facilitate communication between them.

He calls this the product A Team.

a-teamCredit: "How to Be a UX Design Army of One"

Having a UX designer on your team doesn't mean that you no longer need to create wireframes.

Finally, Dan advises that having a UX designer on your team doesn't mean that you no longer need to create wireframes. Wireframes are essential as a means of communicating design ideas to other members of the team. He believes that wireframes are so important because they're usually the first non-textual design artifact that's created. Without wireframes, "you and I can violently agree on 10 user stories, but in your head you're thinking of one UI and I'm thinking of a completely different UI."

The current state of UX

We then shifted gears because I wanted to hear his thoughts on the state of UX design as someone who is steeped in it every day. I asked him about the recent spike in interest in "Customer Experience" as well as his observations on the maturity of UX in the organizations he sees.

On "Customer Experience" (CX)

Dan confirmed what I had observed casually, that User Experience discussions are now being broadened to include the entire Customer Experience. He said, "CX is growing in prevalence in job titles" and mentioned that he has seen positions advertised with titles like "Chief Customer Officer" and "VP of CX".

I asked him why he felt this was happening.

Dan said, "I think the bar is being raised" because customer expectations are higher and there is more competition across all aspects of the experience. He feels that this is true for both for user experience and customer experience overall.

Customer expectations are higher and there is more competition across all aspects of the experience.

Additionally, you can no longer just release a product and leave it at that. "You need to get feedback and see what's going on."

He continued by saying that customer experience can mean different things based on the industry. A small app developer, for example, may not really think in terms of "CX" because for that developer "the Venn diagram of what is CX that is not UX is small," but large companies that sell products in stores have so many more customer touchpoints, including retail, call centers, etc. These companies are likely to think about customer experience more broadly.

For these large companies, aggregating data across disparate experience channels can be a huge challenge. But having a voice-of-the-customer channel can be incredibly powerful. When somebody first catalogs the customer's experience across the different touchpoints it can be a shock, he says, because they are so different. "Usually when you do that first audit it's pretty eye-opening."

On design maturity in the real world

Finally, I asked Dan about the state of User Experience across the organizations he talks to and works with. He explained to me why he is such a big fan of wireframing, and why it's the first thing he recommends to most of his clients, by talking about the different levels of his design maturity model.

ux-design-gapCredit: "How to Be a UX Design Army of One"

Dan talks about the UX design gap in many organizations. "The most common situation you see are teams that only have developers, there's not even a product person. There's certainly no designer." The next level up is developers and a PM. In both cases they are probably not creating wireframes, so you get a lot of different ideas about what the product is going to be. He continued, "even when you add a visual designer, they go straight to Illustrator and Photoshop," so the communication barriers during the development process still exist.

"The most common situation you see are teams that only have developers, there's not even a product person. There's certainly no designer."

He said that frequently, "it's not until you get a UI designer or a PM who knows [Balsamiq Mockups] that you get wireframing as part of the process." This is one of the reasons why he calls Balsamiq Mockups "the best $79 you'll spend," because wireframing is something that anyone can do, but that many small or new organizations don't do or even know about.

Even within teams that have a UX designer, he said that many companies are far from mature. I mentioned the UX blogs I follow and how they can make it seem like everyone is really pushing the envelope in UX. He said that's not the norm, saying, "it's a typical bell curve. You're looking at the 3 sigma people. Those are the people writing about it and debating the finer points of doing it this way vs. that way."

He's observed the same thing for programming languages and technology choices. The business or idea people he talks to just want their idea executed on, they don't necessarily know or even care about the technology used to build it. He told me that for a lot of non-technical founders, the decision about which language to use should be driven more by practical support for it, the ecosystem around it, and the availability of developers who know it.

It's a great time to be building digital products

We wrapped up our conversation by discussing what Dan is most excited about right now. He told me, as someone who has been creating software for 20 years that now is a great time to be building products because of the tools that are available. These tools not only optimize workflows for specialists, they also mean that for small teams, you don't have to be an expert in everything.

There are a lot of tools available now, and many of them are very good. He said, "good tools are popping up left and right... Within the A/B testing space alone, there's all this competition." He continued, "just like customers benefit when there's competition in a product market, product builders benefit when there are a lot of choices and competition in the tools market."

"Just like customers benefit when there's competition in a product market, product builders benefit when there are a lot of choices and competition in the tools market."

Comparing today to the old ways, he said, "I've been there when Marketing is asking Dev to change some HTML. Marketing is frustrated that their little HTML change request has to go through the normal product pipeline - get prioritized, who knows when it's going to get launched - and Dev is frustrated, they're like, 'Are you serious? I want to be coding cool algorithms, I don't want to be changing HTML. That's not even coding'."

But with today's tools, like modern CMS systems, "now, all of a sudden, Marketing can make those changes. Everyone is happy."

He also mentioned the trend towards increasing integration across tools and services. "Most people think about integration right out of the gate," he said. "You can integrate a lot of these tools to help you optimize your product easily."

Finally, he said he's excited about the data that you can get out of the tools. Product debates no longer have to be so subjective. In the past it could come down to people's opinions about a feature. "Someone would win and that's what you would launch. Now you can actually get data with A/B testing. That's also raising the bar." He concluded by saying, "if you can get answers, instead of having to speculate, then the products are going to get better."

Thank you, Dan, for generously sharing your knowledge and expertise. You are a Champion!

Interested in hearing more of what Dan has to say? Follow him on Twitter, LinkedIn, or check out Olsen Solutions. You can also see many of his presentations posted on SlideShare. Readers in the San Francisco Bay Area can join Dan's new Lean Product & Lean UX Meetup group, where he will be speaking on March 18th.

Are you a Champion who wants to be featured on our Balsamiq Champions blog? Send an email to with your stories or blog posts!

From Product Trainer to Product Owner: Craig J Willis's Story

Craig J WillisOur latest Champion is Craig J Willis. Craig is a long-time Mockups user who has used it in both enterprise and, now, startup environments. He wrote to us to tell us one of his Mockups success stories that resulted in him taking a big leap and scoring some major UX victories within his previous company.

After Craig told me his story, I thought it would be useful to share since it demonstrates how he was able to transform a development culture by focusing on the user experience and designing around it. His story also highlights that people most often suited to fix something are those who use it every day, which frequently aren't the developers or "owners" of the product.

But it is also a bit of a cautionary tale, exposing conflicts between ideals and realities of shipping commercial software (especially enterprise software) and explaining why User Experience can still be a tough sell in some organizations.

Seeing usability problems first-hand

Craig was on the education team for an enterprise software product with a large company. His job was to train customers on how to use the product. He knew how powerful and genuinely useful it was, but also knew that new features were continuously being added while the number of requests was growing daily. It was becoming increasingly difficult to consider the impact of every change. Something had to give.

All of the effort was being put into the business logic and very little into how everyday users might actually use it. This meant that all of its idiosyncrasies and faults became magnified every time a new feature was added. Craig said that in the focus to satisfy every customer request there just wasn't enough thought about the future of the product among the development team, they just kept adding on while making sure that everything still worked. "There were a lot of stop‑gaps."

That's not to say that the team was clueless or mis-guided. It can be hard to know about a product's usability problems without using it regularly, yet involving customers in the process can also be troublesome. Customers have a hard time imagining a different way for the product to behave, so they are more apt to ask for features rather than workflow improvements. But having the input of someone who teaches it to others can be very useful. They have to explain how to do things with it over and over and can't help but think of ways that it could be improved. Craig was just that person.

Craig had become frustrated trying to explain to customers the convoluted workflows and work-arounds required to use the product, knowing that there was no satisfying explanation for it. He also thought about how much time and money was being wasted getting customers up-to-speed on what should have been intuitive actions. He frequently complained, but wasn't in the right position to have any influence.

I was like 'guys, we've got a much bigger problem.'

One day he overheard some people from the product team talking about hiring a design firm to give it a design overhaul. He got very excited. As Craig told me "I made sure to get invited to that meeting." In the meeting he was amazed to hear them spending "lots of time talking about fonts and colors." He knew that a fresh coat of paint wasn't going to solve the usability problems he knew all-too-well. He told me "I was like 'guys, we've got a much bigger problem.'"

In the meeting, when he said that the product was hard to use, he didn't get very far. But when he showed how it could be made better, people immediately saw what was wrong with the current product. He used Balsamiq Mockups to redesign a few screens so that he could show them how the workflow could be improved. Much like Michael Bourque, Craig used Mockups to tell a story about his vision for the product. This approach was so successful, in fact, that he was asked to take charge of the product right then and there. Craig told me: "I showed them what I was talking about and they made me Product Manager."

Thrust into the spotlight

Craig's promotion to Product Manager cast him in a very different role. He was now responsible for seeing through all the changes he had been suggesting. He learned how difficult it would be to put his obese product on a life-changing diet.

'No' wasn't a word the team was used to hearing.

He began by saying no to a lot of feature requests, which didn't make him very popular. He says "I became one of the most disliked people at the company. Previously we had accepted and queued up every request. 'No' wasn't a word the team was used to hearing, but now they had to hear it from me, frequently."

This wasn't the only change. Craig was using visual mockups to communicate the development plan, whereas in the past they had used giant specification documents containing only a few screen shots, so it took some effort to convert people to this leaner way of doing things.

He persisted. He extolled the virtues of User Experience Design by quoting Don Norman's "The Design of Everyday Things" in meetings and by educating people on the difference between aesthetics and User Experience. This slowly got him the approval to spend development time to improve the User Experience.

To get the redesign rolling, again he turned to Balsamiq Mockups. Craig told me that they created mockups for 70-80% of all the screens in the product, which was a lot. Using them, he reached out to the sales team to vet his ideas. He then involved the development team to assess the feasibility of his designs. This iterative approach helped bridge the gap between the teams who knew what customers were having problems with and the teams who knew what was achievable in the time they had.

Don't think about what it looks like, look at what it's doing.

While most people got very excited when talking over Mockups, from time to time he'd still get asked "why does this look like a sketch?" Craig had internalized all of the User Experience literature he had read and would respond by saying "don't think about what it looks like, look at what it's doing". Again and again, he went through this process until everyone was on the same page and they had "ironed out" the usability and technical tradeoffs associated with the new design.

In fits and starts, the product began to transform into a more usable product that fit its users mental models better, yielding major UI improvements. It was released earlier this year and has been very well received by customers. Here are some screenshots of one of the mockups and the corresponding final product:



Lessons learned, applied to a new endeavor

Armed with both his experience as a product trainer and product manager, Craig and a partner recently ventured out on their own to improve the experience of capturing requirements for Agile development teams. They are setting out to fill in some of the gaps they've seen over the years in tools designed to support Agile development. Their new product is called Skore. It is a visual tool that makes writing and creating Agile user stories quick and easy. It cuts out many of the steps and simplifies it to the point that stories can be created in real time during meetings and conversations. Learn more about it at

Are you a Champion who wants to be featured on our Balsamiq Champions blog? Send an email to with your stories or blog posts!

Using Mockups 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 Mockups 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 Mockups go great together. Agile is fast, embraces change, and doesn't require precision. Just like Balsamiq Mockups!

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 mockup 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 Mockups.

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. Mockups 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 Mockups 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 mockup 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 mockup 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 mockups 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 mockup 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. Mockups 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 mockup 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 mockup 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. Mockup
  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 mockup is done (label changes, etc.). Even though updating the mockup 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 mockup, 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 mockup, 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.