Edit the Balsamiq Docs!

We've made it easy for anyone with a Github account to submit edits to our documentation.

As we've written about before, improving our documentation has been a focus of ours for a while. We've gone from one or two developers writing docs when they found the time to a team of about five people that make sure the docs are updated with each release.

We recently updated our docs site (sites, actually) to be easier for both readers and writers.

This year I attended the Write the Docs 2016 conference in Portland to learn from other writers. I also spoke on a panel discussion there to share what we learned through our documentation overhaul. And our documentation repositories are public so that anyone can use them as a starting template.

Looking at open source software projects we use and talking with other "documentarians" whose docs are on Github, I noticed that many projects invite documentation collaboration from readers via Github "pull requests". Since our docs are on Github, we decided to do it too.

We aren't an open source software project and we don't rely on volunteers for our work, but we often get emails about our documentation; Typos, text that's not clear, or out-of-date information, for example. Now, with a Github account, you can propose those changes directly in our documentation!

Here's how.

At the bottom of each article on docs.balsamiq.com and support.balsamiq.com you'll see a link called "Edit this page".

Clicking that link will take you directly to the Markdown source for that specific page in our repository.

To propose a change, click the "edit" icon to "fork" the repository. (You have to be logged into Github to do this. If you don't already have a Github account, learn how to sign up here.)

You can then edit the file. Add a brief explanation of your changes and click the "Propose file change" button to submit it.

Once you do that we'll immediately get notified and, if we agree with the change, we'll merge it into our "master" branch and it'll be live.

Since we added this, we've already had one contributor, Song Li, who fixed a link in one of our Sales FAQs. Thanks, Song Li!

And thanks in advance to our community documentarians who will use this feature. You're helping to make our documentation better for everyone.

In Case You Missed It: New Hidden Powers in Balsamiq Mockups 3

Finally getting to work on features that have been on the back-burner forever is a great way to rejuvenate developers and reward long-time customers.

After a slow year of public releases in 2014 while we re-wrote our product from scratch, 2015 and 2016 have been chock-full of updates (4 major releases, 31 minor ones).

I thought it might be useful to recap some recent new features we really enjoy that you might have missed. In this post I'll provide some back-story on the "Quick Draw" and Transform control features from our 3.2 release.

You can see them in action here:

These were ideas that had been in the back of our minds forever that we finally implemented. It felt good to get them out there. Read on for the story behind them.


Anyone who works in software has a list of ideas that start with "wouldn't it be cool if...?" These ideas often take a long time to make their way into the product, if they make it at all. Some possible reasons:

  1. They're just plain hard or time-consuming
  2. Customers aren't actually asking for them, making it hard to justify the work (though they may be complaining about problems that these ideas would solve)
  3. Stability and performance issues and "must have" features take priority

With our 3.0 release, Balsamiq Mockups settled into the usable and useful product that we originally conceived it to be. This freed us up to start working on some exciting "wouldn't it be cool if..." features.

We want to collapse the time between when an idea forms in your head and when you see it on the page.

We use Balsamiq Mockups internally a lot, so we are always looking for faster and more efficient ways to wireframe. Our standard for getting into the flow is paper and pen, after all. Our 3.0 release was designed to be simpler and more powerful. Our 3.x releases have been focused on speed. We want to collapse the time between when an idea forms in your head and when you see it on the page. That's what motivated us to build the following features.

"Quick Draw"

Balsamiq Mockups 3 brought more visibility and simplicity to things like Symbols and assets. But the core workflow of adding controls to the canvas remained similar to previous versions. For a long time we envisioned a workflow that would allow you to build up your wireframes before even having a concrete plan for the UI details.

Starting with an outline

Ideas don't always come fully-formed. We thought about drawing outlines on the canvas, like you would on paper, to create a skeleton for an idea that was still being developed. We already had placeholder controls in the UI Library, such as the rectangle and image controls, and lorem ipsum text in a Text control, but using them still required dragging onto the canvas and then resizing them.

What we really wanted was a way to "draw" directly onto the canvas.

What we really wanted was a way to "draw" directly onto the canvas. We decided right away that freehand drawing with a mouse is non-optimal. It's imprecise and forces you to slow down quite a bit when you do want precision (such as connecting lines to close a gap). So we moved on to click-dragging, holding down the mouse button while dragging (they way you "lasso" multiple controls in many drawing programs, including ours).

After some experimentation and discussion, we decided that holding down a keyboard modifier key while click-dragging was a sufficiently intuitive way to "draw" on the screen. We used the "R" key for drawing a rectangle, the most generic control in our palette.

Better placeholder text

Our next thought was to make it easy to add placeholder text to your mockups using this method. But our existing headline and paragraph controls didn't lend themselves to it well. They were a fixed size and optimized for resizing only after you'd entered text in them. Again, we wanted to quickly be able to add a placeholder without having to think about content.

Our solution was to add two new controls - "Line of Text" and "Block of Text". These were features that had been requested many times over the years. "Greeking" text is often used in wireframing to create placeholder text without using recognizable letters that would distract viewers.

New controls make it easy to show placeholder text

Putting it all together

With these new controls added to our UI Library we could now assign modifier keys to them and allow users to draw them onto the canvas. We used "T" for the block of text and "Y" for the line of text (a.k.a. headline).

Here's what it looks like:

We immediately fell in love with this feature. It felt like something we'd been missing all along. We are always striving to make our tool simpler, more "basic" even, and this felt like a great way to "add less" to our tool (without making it more difficult for people who didn't use it). In other words, it met our criteria for "hidden powers".

Transforming Controls

For speed and efficiency, our new drawing feature had one major drawback. When you decided what to replace the placeholders with, you would have to delete them and re-add specific controls. This was a step in the wrong direction. So we added one other major "wouldn't it be cool if..." feature that had been on our back-burner. One that seemed out of reach at times due to the complexity.

"Wouldn't it be cool if you could swap out one control for another?"

It went something like this: "Wouldn't it be cool if you could swap out one control for another?" A key part of wireframing is iteration: discussion, changing your mind, trying something out to see how it feels. A common example is building a form and then deciding that a text field should be a drop-down box. Not a big deal to delete it and replace it, but across multiple mockups, projects, years, it adds up.

Yes, but how?

But, and here's the tricky part, what should the logic be to transform one control to another? Changing a text input to a combo box? Definitely. A rectangle to an image? Sure. A tree control to a list? Or an accordion? Hmmm...

Peldi likes to say that he loves mundane, repetitive tasks of all kinds. How about mapping each of our 70+ controls to each other one, deciding whether it should be transformable to that control? It required persistence and expert knowledge of the product inside and out, clearly a job for Peldi.

His spreadsheet ended up looking like this:
swap-control-tableA boring chore for an intern? Actually, it was done by our CEO.

With that laborious task complete, we started the work to build it.

Getting it right

In the spirit of "hidden powers," we didn't need it to scream for attention. It's not something you should be distracted by when you're in the flow. So there's no big button in the UI that says "Click Me to Transform!" Just a subtle arrow in the Property Inspector and an item in the right-click menu. There's also a handy keyboard shortcut (CTRL/CMD + T) for when you're ready to start using it regularly.

Check it out:

Finally, we decided that some controls could even transform on their own. Like turning a placeholder text control into a real text control. So, if you type into a block or line of text control it automatically transforms to a paragraph or subtitle control. Neat!

See it here:


These are two of our favorite recent features, but they're not the only ones that we've added to help you work faster and more efficiently.

In 3.1 we introduced Alternates and Background Music. 3.3 provided the ability to organize mockups into groups, like this:

"Nested" mockups

And we finally made arrows that work the way you expect!

Earlier this year we also added the ability to automatically generate Site Maps based on the mockups in your project. This was another "back-burner" project that we really enjoy using.

Deciding what to work on

One of the hard things about software is that it's never finished. Our 3.0 release felt "complete" yet we knew we could continue making meaningful improvements (not to mention the hundreds of small enhancements and bug fixes). However, we resisted adding features that didn't feel central to the purpose of our product or that would make our product harder to use.

Instead we chose features that we were excited about and that we knew our long-time users and fans would appreciate. Sometimes that's just what feels like the right thing to do. We are grateful to our community of bug reporters, support callers, and forums users who have provided feedback and guidance along the way.

We are now hard at work on another very exciting project, native versions of Balsamiq Mockups! Stay tuned!

Free Course on Wireframing with Balsamiq Mockups on Udemy

We now offer a free course on Udemy called Wireframing with Balsamiq Mockups. It's designed to cover the basics of what Balsamiq Mockups is and how to get started with it. It will walk you through the primary features and show you how to create a simple project.

The course contains 8 video lectures that build on each other to get you feeling comfortable and confident with Balsamiq Mockups in less than one hour. It's designed for anyone who is just getting started with Balsamiq or wants to learn how to use it more effectively.

All you need for the course is the free 30-day trial of our desktop version (or a registered version if you already have it).

Head on over to Udemy and start learning now. :)

— Leon

Docs.balsamiq.com: Our New Static Documentation Site, Powered by Hugo

Last month we released a brand new web site for our documentation - docs.balsamiq.com. We also updated our support site with a new design and layout. This post describes what we did and why we did it.

docs.balsamiq.comThe new Docs.balsamiq.com


Early last year we wrote about how we updated our support website for a better user experience. This included customizing our support center template to make it easier to browse and navigate, and putting more focus on tutorials and step-by-step guides. We also put in place some systems for writing documentation to streamline the process internally.

Since then a few events led us to want to improve our support and documentation site even more.

  1. Moving our balsamiq.com site from WordPress to a static site
  2. I started using Markdown for blog posts and documentation (and then converting it to HTML for publishing)
  3. Increasing frustration with our existing knowledge base system, which made changes live as soon as they were saved and had a clunky editing experience
  4. Search wasn't very good, making it hard for people to find what they were looking for.

Each of these factors alone probably wouldn't have led us to create a new support site, but combined they provided enough impetus to justify the work to move our content over to a new system.

Making a Plan

Before diving in, we made a list of requirements for our as-yet-undecided solution. They included:

  • Versioning so that we can review history and work on updates before publishing them
  • Ability to automatically generate a list of articles in a given category (for creating a table of contents)
  • Customizable templates for different page types (article, TOC, main index, etc.)
  • Support for Markdown
  • Support for in-page anchors (automatically generated would be nice!)
  • Next and previous buttons/links to articles within a category

A few of us researched options and we discussed the merits of each. Around that time a few other events led us converge on a plan.

Mike blogged about converting his personal site to Hugo

These three things gave us the confidence to start a project to convert our existing documentation to a static site built on Hugo.

Designing the Experience

We started a myBalsamiq project for the site and created some wireframes for the layout, navigation, and content.

Our primary design goals were to make it easy to navigate and to remove as much unnecessary stuff as possible.

An early layout. We eventually decided to combine the sub-section navigation and in-page navigation areas.

After some discussion, we decided to separate our documentation articles from our support articles. This would allow us to have one dedicated site for our user guides, which are there to help our users learn the product. Our support site, on the other hand, is where people can go when they need help or have a specific question.

This also allowed us to make the transition faster, since only the documentation site would be built on Hugo.

These designs show our concept right before implementation.

Along the way, Mike took an opportunity to work on updating our existing support site design.

The updated Support.balsamiq.com

Implementation and Go-Live

Because several tasks had to be coordinated, Mike, Peldi, and I blocked off two days last month for the "launch-a-palooza" where we updated articles on the support site, switched to the new template, added the redirects, and a bunch of other behind-the-scenes stuff.

For the finishing touch, Peldi implemented a new search engine, Swiftype, across all our sites (not just our documentation and support sites). This was awesome, since it helped bridge the gap between our two separate help sites.

Finally, we decided to open source our documentation site code.

We are now working on converting our existing support site to Hugo, which, thanks to the work we've already done, shouldn't be too much work.


As the primary documentation writer, I was the person here who wanted this project the most and the one who has benefitted most from it. But I was also the most resistant, because it seemed like a lot of work, and I was concerned about all the old links, worried that many customers would be seeing our Sad Robot instead of getting the help they needed.

But Peldi and Mike's experience with large web projects made it happen and they knew how to handle all the details and loose ends to make sure the transition was by-and-large incredibly smooth. On top of that, Mike's excellent design work and Peldi's implementation of our new search capabilities made the end product better than I could have imagined.

I'm not sure what the rest of our company learned from this, but I learned that having the right team on a project can produce great results. I don't think I'll be so intimidated the next time I'm faced with an idea for a large project.

I think it's also important to note that, while much of the work on this project involved using new technologies, we did a lot of work up front to define the problem and write down what we expected from our solution. This project wasn't just a show of our technical capabilities, but our effort to improve our products and processes by making documentation easier for our writers and better for our customers.

Thoughts? Feedback? Feel free to share in the comments!

- Leon

Tips for Presenting Your Wireframes

Now that they're done, what do you do with them?

I recently wrote an article for the Treehouse Blog called "3 Steps to Better UI Wireframes" that provides some wireframing tricks that I've learned in my career as a UX designer.

The three steps I outlined were:

  1. Get into the Wireframing Mindset
  2. Take Your Time
  3. Build a Bridge from MVP to 3.0 (or the Other Way Around)

In this post I'll be following up on those steps by describing some techniques for being prepared when the time comes to present your wireframes to clients and stakeholders.

The Other Customer

As a designer (or temporary wearer of a designer hat), you need to jump into the mind and world of the end user. The user is the ultimate customer of your wireframes, and your job as the designer is to create something that solves their problem in a way that makes sense to them. But the end user is not your only customer. In the vast majority of cases (unless you are a one person operation) your designs will need approval from someone else (possibly many other people) to proceed. It could be the developer who will be writing the code, the Product Manager who owns the project, or the clients who may (or may not) be buying your product.

ST042: Figure 15.13

Image credit: "Storytelling for User Experience", ©Rosenfeld Media

In one form or another, you need to get "buy-in" on your designs. Many young designers often incorrectly assume that getting the go-ahead on their work is achieved by creating the best design possible. Great design should be obvious to everyone, right?

Not so fast.

Tom Greever, author of the book "Articulating Design Decisions", states:

Your ability to be thoughtful about a problem and articulate any solution is more important than your ability to design the perfect solution every time.
- Tom Greever

My experience backs this up. Read on for some tips for presenting effectively once your wireframes are done.

1. Be Open to Changes

After working hard on an awesome set of wireframes, the last thing you want is a critique of them. But you have to learn to be ready for your "presentation" to be more like a conversation. Your design might be very good, but accepting input from others can make it even better. Being in the right mindset will make it feel less like criticism and more like consensus-building.

If you go in being open to suggestions you'll come out with a better final product.

Here are a few ways that you can lead the inevitable feedback you'll receive.

Admit your uncertainty - Just like with any presentation, being humble helps get the audience on your side. You may be presenting to subject matter experts and if you come off seeming to know absolutely everything you can sound smug or cocky. Talking about some areas of your design that you're unsure about or, better yet, inviting suggestions from the audience, can build a collaborative atmosphere. Incorporating another person's idea will give them an investment in the design and turn them into an advocate for it.

Have alternates prepared - If you expect that people might not like some part of your design, have some alternates ready to show. It's better to show that you've considered other ideas than to let people think that you threw something together casually. If you've taken your time, then you should have some alternate or abandoned ideas to show. Don't be afraid to show something incomplete (including paths you gave up on). Describing why you chose your primary design over an alternate will help justify it.

Showing this evolution — what designs died and which ones survived — helps substantiate the final result. It shows you have explored options, not just executed on the first whim.
- Todd Moy

Try making some changes live - If you've got a really lively crowd, stop the presentation and have a mini design session. Open up Balsamiq and make some edits to your wireframes directly!

2. Provide Context via a Timeline

In the vast majority of the cases, there is something that led up to what you're presenting. A previous version, an existing tool, or prior work on the same project. Start there before showing your designs. Give a "recap" of the project to date.

Show the audience how what you're about to present fits into the context of the project as an evolution toward a final goal (even if it's part of a much larger goal).

This can include fast-forwarding to what you'll be working on next. If you've taken the approach of building a bridge to or from your "3.0" vision, then you can even show a glimpse into the future to help show how your design brings the product closer to the end goal.

Doing this will show how what you've designed fits with the previous work, or is an improvement over it, and how it connects to the next steps or lays the foundation for them. Show your design as a stepping stone on the path that everyone wants to be on.

By doing this you are incorporating a few established UX techniques together:

  1. Telling a story
  2. Answering the question: "Why are we doing this?" - what the PM or CEO cares about
  3. Clarifying that you understand the interests of everyone involved.

3. Be Ready to Talk About Your Design Choices

Finally, be prepared for some push-back on your work. Sometimes it's because you missed something, that there was something you hadn't thought about (in which case you can ask for help from the audience, as described above), but resistance also arises because good UX challenges assumptions. The best design is frequently not exactly what the customer asked for. If you've done your job and studied the problems that customers have, rather than only the features they ask for, you may be proposing something unexpected. In any case, be ready to defend, or at least discuss, the design decisions you made.

Returning to Tom Greever's work on articulating design decisions, he suggests a list of common explanations, or justifications, for why design decisions are made. They are:

  • Facilitates a primary use case
  • Follows a common design pattern
  • Meets a particular goal
  • Data supports it
  • Complies with a standard
  • Limited by technology
  • Draws the user’s attention
  • Creates a flow for the user
  • Establishes branding

I have found the first two in particular - "facilitates a primary use case" and "follows a common design pattern" - to be especially compelling.

You first need to get in the habit of justifying design decisions to yourself. Returning to the primary use cases (you do have these, right?) and following established UI patterns are excellent guiding principles. If you've followed these during the design phase, you should definitely mention them during the presentation. Depending on the project, product, or audience, the other explanations may be even more effective.


If you've done your design work correctly you've taken the time to step into the shoes of the end user. Presenting your wireframes is the time to step into the shoes of your intermediate customers, your presentation audience. You may care about how it looks and how it works, but your audience may care more about how long it will take to build, whether it can be built using their tools and frameworks, or whether it can be marketed successfully.

So, once your wireframes are done, take some time to review the assumptions you've made along the way, go back to your notes from meetings before you started designing, try to anticipate how your audience might respond, and review the tips above.

Good luck!

How We Got Here: The Road to Balsamiq Mockups 3

The release of Balsamiq Mockups 3 was the biggest release in our history since the original product launch in 2008.

For this release we took a leap of faith and went nearly an entire year without releasing any real product updates (in comparison we released about once a month in 2013). At our annual retreat last year after not releasing any feature updates in nearly six months Peldi had to reassure us that we were still doing the right thing and to stay the course.

And fortunately people were still buying our product.

We also made up for the lack of Mockups for Desktop updates with big improvements to Mockups for Google Drive (yay, Sax!), and lots of updates to myBalsamiq and our website, documentation, and blogs.

This post is all about how we got to Balsamiq Mockups 3. It was a windy, bumpy road, full of changes in direction, fits and starts, delays, and uncertainty about the final product. (So, in other words, a pretty typical software development project.) But when we neared the end it all came together rather beautifully in a way that validated our organic and intuition (rather than market)-driven approach.

2011-2013: Mockups “Pro”

Long before any planning or design started we referred to the next generation of our product internally as “Mockups Pro.” This was convenient because we all agreed that our next major version would be Pro, even though we had different ideas about what “Pro” actually meant. Pro was either an abbreviation for Projects (bundling multiple files and assets into a single project file) or Professional (a separate, more feature-rich version of our product for heavy users) depending on who you talked to.

In late 2013 Peldi decided Balsamiq Mockups version 2 was stable and feature-rich enough to start something new.

Mike had already been working on a UI overhaul as a side project and kicked things off with a comp to give us some inspiration.

The “Pro” idea and Mike’s vision of improving the appearance and standardizing the interaction provided the fertile ground for us to start our next adventure.

We knew that the next version was not just about adding features or a fresh coat of paint.

But we knew that the next version was not just about adding features or a fresh coat of paint. So we began with some important questions that kept us focused throughout the project.

From a wiki page created in 2013:

  1. How we can evolve it [Mockups] without breaking from what’s become “the ethos of Mockups?” There is a definite character we want to hold on to, while maturing it. People want that.
  2. What things should not change on the surface?
  3. What things should not change about the experience?
  4. What things are so effective that they create “Flow” when using the app?
  5. What are the things that contribute to a sense of effortless and ease (and effortless effort), as if “the wireframes just make themselves?”

These questions and some heavy discussions lead us to a set of design principles and the following guidelines for our next project:

  1. Stick to our basic identity (that had made Mockups successful in the first place)
  2. Make it easier to use (especially by reducing friction around pain points)
  3. Introduce professional and power-user features without overwhelming the UI

And, with that, we moved on to…

2013-2014: Mockups 2.5

We knew that before we got any further we had to settle the “Pro” debate once and for all. Should we create two separate versions of our product, one for occasional users and another with more bells and whistles for “professional” users?

We started out thinking that we would. For a long time we maintained a separate feature tracking project for only “Pro” features. It contained every “wouldn’t it be cool if…” big idea that customers and employees had suggested over the years.

But something was holding us back. I think it was more a gut feeling than anything else, largely coming from Peldi and Mike. On a wiki page called “Future of Mockups User Experience” Mike summarized Peldi’s concerns as follows:

Peldi had a simple vision for Standard [the non-Pro version] that he was excited about. He isn’t excited about a tool that essentially comes close in appearance and function to graphic design tools like Photoshop or prototyping tools like Axure.

Clearly a more powerful tool could be both useful and profitable, but was it something we were excited about building? Fortunately, our decision to remain small and independent allowed us to ask this question rather than just thinking about what would bring in the most money.

Then there was this action item further down the page:

Go back from the start and ask “why did we think of doing a Pro version in the first place? What are the things that just don’t belong in Standard? What problem are we trying to solve with Pro?

This question of “what problem are we trying to solve?” has frequently shown us the way in times of indecision. And this time it reminded us that Peldi’s original vision hadn’t really changed - to help rid the world of bad software by allowing anyone to quickly and easily visualize their product ideas.

This question of “what problem are we trying to solve?” has frequently shown us the way in times of indecision.

So we decided to channel our efforts into building an update to Balsamiq Mockups that retained the current core functionality and ease but alleviated pain points and cruft that had accumulated as the product had grown.

The Pro label disappeared and the project was dubbed “Mockups 2.5” (the current version was 2.2) since it felt like a big, but not HUGE (e.g., full of new power-user features) update.

Mike created some quick comps that didn’t look radically different from the existing version at the time, Mockups 2.2.

Our focus narrowed to a few specific targets addressing our customer’s biggest frustrations:

  • Support for bundled project files instead of separate files for each mockup
  • Improve the usability of Symbols
  • Redesign the UI layout for a better editing experience (including figuring out what to do with the floating “property inspector” window/widget/thingy that bugged everyone so much)

We made a list of additional features that we'd then work on in "follow up releases."

After many rounds of iteration we started building it and had a working build ready in a relatively short time.

Here’s an early demo from a test build.

Mockups 2.5 was nearly ready.

But were we?

2014: "Panels" + "BMPR" = "B3"

Indecision returned as we reviewed our concepts and requirements. What should this release include? We discovered that there were so many things that we were excited about building into the product. Auto-save? Yes! Project notes? Yes! Preferences dialog? Still no. JSON instead of XML? Yes! Default font settings? Yes! Trash? You get the picture...

It was starting to sound like a pretty big project. Too big for a “minor” (a.k.a. “dot”) update…?

We left that question alone and went back to something more certain. We knew that we wanted the UI layout to have the mockups on the left, the canvas in the center, and the UI Library and Properties on the right. So we just started calling what we were working on Panels because of the UI “panels” on the left and right.

Our high-fidelity "vision" comps gave way to detailed high- and low-level wireframes describing interactions, flows, and layout as we fleshed out more details.

Peldi created a video walkthrough of some of his mockups for the Panels UI.

Notice how effective a simple click-through wireframe deck can be when accompanied by someone walking you through it? This is an example of the design workflow we promote. We generally don't see the need to create high-fidelity, fully interactive prototypes to convey our ideas and this project was no exception.

We generally don't see the need to create high-fidelity, fully interactive prototypes to convey our ideas and this project was no exception.

Peldi, Andrea and Michele were also deep into cleaning up the code at this point, looking at everything we had written in the last 7 years. They consolidated, removed and beautified code until it was actually readable and much more efficient. The clean slate gave us the energy to think more ambitiously about both the back end and front end.

This included a rewrite of our file format to accommodate the exciting new things we wanted to add. Marco and Paolo were borrowed from other projects to help. This spawned architecture diagrams, flow charts, and developer mini-retreats. Meanwhile, the UX team was discussing the toolbars, menus, icons, etc...

Finally, near the end of 2014 we started playing with test builds and trying it out internally. We called it "B3" (for Balsamiq 3). We'd talked about dropping "Mockups" from the product name for a while, since nearly all of our customers just called it "Balsamiq." Plus, what it creates are more accurately called wireframes than mockups. But it turned out to be a pain to change the name for a variety of reasons, so we called it Balsamiq Mockups 3. Although now we were more relaxed about just calling it Balsamiq in conversation. ;-)

Late 2014: Ready for Feedback

We all felt that we had built something that was both more powerful and more elegant than the current version of Mockups. But we had no clue if our customers would feel the same way. It wasn't only a question of would they like it, but would they like it enough to switch, which would include learning some new things and, not insignificantly, converting their old files by importing them to the new format.

As we had done in the past we reached out to some of our long-time champions and friends for a closed beta test. We also conducted a formal usability test with help from Mike Heraghty at User Journeys. This uncovered a lot of technical and usability bugs and gave us some great qualitative feedback, including what to expect from people’s first impressions.

After a few more rounds of fixes and tweaks we felt like it was ready for a bigger test. On February 2nd, 2015 we announced the public beta and opened up our new community forums to talk about it.

While it was hard to take some of the tough feedback, the overall feeling of connecting and communicating directly with customers was energizing. For the old-timers at Balsamiq it took us back to the early days in the GetSatisfaction forums around version 1.

And the public beta lead to some great improvements in a short amount of time.

For example, the UI Library and Properties panel sharing the same space that we thought was so clever? It turned out that our customers didn’t agree. So we moved the UI Library back to the top.

Other notable additions during the public beta were Font Awesome icons and the Project Information panel, which included highly-requested settings for changing the default font and selection color.

Releasing without beta testing first would have been a disaster.

We are so grateful to all of our beta testers for their time and patience. Releasing without beta testing first would have been a disaster and we feel so fortunate to have customers who wanted to help us make our product better.


March 10th, 2015: Release day! There were some hiccups, as expected, but it generally went very smoothly. And we had all-hands on deck to respond to issues that showed up upon releasing to a broader group of users. Two weeks later we released an update addressing most of them, followed by three more updates over the next few weeks.

Less than two months after the official release, we don’t know whether Balsamiq Mockups 3 will be a success for us. We know that we enjoy using it ourselves and that many of our customers do too. But we are hopeful because we followed a process that has worked for us in the past: a mix of passion, focus and openness that feels intuitively right to us.

If I had to distill from this entire process a few lessons we’ve learned from building this and other products it would be these:

  1. Build something you’re excited about
  2. Define the problem you’re trying to solve early on
  3. Involve your customers in a meaningful way at some point in the process

We’ve come a long way since 2.0. Thanks SO MUCH to all of our loyal (and new!) customers. We want Balsamiq Mockups to be a product that you love to use, so please let us know what we can do to make it even better!

- Leon for the Balsamiq Team

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!

Mockups Tips for Getting Unstuck

It happens to all of us. You get stuck. You're stalled on a design and don't know what to do next. Or you find yourself using the same tired design pattern over and over again, though you know there's gotta be a better way. And then there's the sneakiest form of stuck: reacting to a feature request by whipping up and sending off the first design that comes to mind without diving deeper into the problem.

These scenarios are frustrating because you know that not only is there a better design out there, there's a better designer inside. You just have to find a way to jar it loose by waking him/her up.

There's no sure-fire way to do this. Every case is different. And sometimes it just clears up on its own. In this post I list a few techniques we've used to kick-start that process using Balsamiq Mockups. Hopefully you'll find them helpful.

Technique #1: Embrace Constraints

There are an infinite number of design solutions for every idea. Yikes! If you think about that it can stop you right in your tracks. But we all know that there's nothing like a deadline or an arbitrary restriction to get things going. Here are some suggestions along those lines:

  1. Limit yourself to 5 minutes (or less!) per mockup. After 5 minutes, create a new one and try to come up with a totally different idea. Repeat. See how many ideas you can create like this.
  2. Try to create 5 mockups in 10 minutes around the same design problem or idea. (Tip: Learn keyboard shortcuts to help you work faster.)
  3. Limit yourself to 10 UI controls. See if you can describe your idea in even fewer; it often doesn't take many to capture it.
  4. A variation on the above: limit yourself to a basic subset of UI controls. Pick the most generic ones (rectangle, button, shape, etc.) and work using only those to focus on the big picture first.
  5. Peldi has said that the first design is often version 3 of the product. Create the wireframe you have in mind then try to remove as many pieces as possible. This will challenge you to think about what's most important and what's not really needed.
  6. Put all the UI controls on the canvas then try to build your mockup. It may help you think of other methods of doing things in the UI (as well as scramble your brain a bit). Move aside the unused ones, but don't delete them right away because you may come up with a use for them later on in the design.

All The Controls!ALL THE CONTROLS! (download this file)

Technique #2: Collaborate

Mockups is great for working together with other people. And most of our products now allow multiple people to work on a single mockup at the same time.

Here are some suggestions for how to get more out of your design by working on it with someone else:

  1. Work on a design for 5 minutes, then hand it off to someone else. The next person can either build on it or modify it. Repeat until you're both happy with it.
  2. Take turns adding UI controls. (You can easily do this in myBalsamiq and Mockups for Google Drive. In other versions you can sit at the same machine or use Dropbox or a shared folder across machines.)
  3. Swap projects with a designer on another team. Have them do one of your designs while you do one of theirs.
  4. Assign multiple people to work on the same design. Do a "show and tell" with time for discussion about each design. Then allow each person to revise their design based on the ideas from others.
  5. Pair design. Have two people sit together and assign one person to describe the design and the other one to use the mouse and keyboard in Mockups. Even if you have a very specific UI/design in mind it may come out different if someone else is building it, and the process of describing it may help you catch some flaws with it.

Collaboration in action in Balsamiq Mockups for Google Drive

Do you have techniques for getting unstuck that you use? Feel free to describe them in the comments!

Behind the Scenes of Our Documentation Process

We recently wrote about some of the changes we made to our support site in the last year. Following up on it, this post goes into depth about the details of our process for adding content to our support site.

As we are a software company, our process for adding documentation is not unlike our process for adding features and fixing bugs. Here's how we do it.

Recording a need

Documentation updates can be prompted by several actions. Here are the primary triggers:

  1. A customer contacts us (via phone, email or our forums) and mentions a typo or mistake in our documentation or has a problem that should be explained better on our support site
  2. We add or change something in our product and therefore need to update our documentation
  3. A support employee mentions that lots of people keep asking the same question and asks to create a dedicated FAQ or article about it

As much as possible we try to track things our customers want to know more about and things they're frustrated by. Our process hinges on frequent communication between our customer-facing staff and our documentation and product people. We also want to make it easy to then record those frustrations as tasks and assign them to the right people. I am responsible for our non-sales related documentation.

The three main tools we use in our documentation workflow are:

  • Desk - for email support and for managing our documentation knowledge base
  • HipChat - for communication among the team, and
  • Pivotal Tracker - for tracking issues and documentation requests.

If an issue related to documentation is raised in Desk (our direct customer support channel), it can be assigned to me. We also have a dedicated HipChat room called Docs, where we discuss ideas for new support articles and give feedback on existing ones.

Some conversation in our HipChat Docs room, including status updates from Pivotal

To stay in the loop I also monitor the Support HipChat room so I that can see what people are having trouble with.

Some conversation in our HipChat Support room

Inside Pivotal

We use Pivotal Tracker for our product feature requests and bug fixes, so it made sense to use it to track documentation tasks as well. For a long time our documentation issues were filed in a general "Website" project, which was a catch-all for anything affecting our website (documentation, page redesigns, CSS alignment issues, etc.). But we recently created a separate project called "Docs" just for documentation and tutorials and moved our documentation stories into it.

We also made it easier to add issues to Pivotal by connecting Pivotal to HipChat via Zapier. Now, when a documentation story is created or updated in Pivotal, it is shown in HipChat (you can see this in the first HipChat screenshot above). Conversely, we can create Pivotal documentation issues directly from HipChat by typing: "Pivotal(issue name)". Employees can also create Pivotal stories directly in our Pivotal Docs project.

Once the documentation tasks are in Pivotal, I can organize them and begin work on them. Organization within Pivotal can be a bit of a challenge though, so I came up with a few additional processes for getting a handle on our documentation stories.


After we separated our documentation stories from our other website stories I quickly reviewed each of them. I started by labeling those I didn't understand as "to review." Those that appeared to be no longer relevant I labeled "to remove." The people who created those stories pitched in and added their comments or deleted them and we reduced the size of the backlog a bit.

Next, I tried to think about how to prioritize and group the remaining stories because I didn't have a good way to get a sense of urgency and difficulty. One of the first things I did (perhaps because diving right in was too intimidating) was develop a labeling system.

After some iteration, I came up with three categories of labels:

  1. The Action label group, describing what kind of task was needed
    • "New" means this is a new article that should be created
    • "Update" means that this is an existing article that needs updating (e.g., out-of-date screenshot, missing feature/function)
    • "Clarify" means that something in this article is not clear and should be reworded or modified for clarity
  2. The Actor label group, describing the type of documentation affected
    • "FAQ" is for any FAQ (product, licensing, installation)
    • "Documentation" is for product user guides (anything in the Mockups for Desktop or myBalsamiq "Documentation" category or any of the plugin User or Admin guides)
    • "Tutorial" is for tutorials
  3. The Category label group, describing the affected product or category within the Actor group (myB, Desktop, GDrive, Licensing, etc.) - this is optional

When adding the tags I try to place the tags in this order: "Action (Category) Actor" so that they make sense when written out. E.g., "New Installation FAQ", "Update myB Documentation", "Update Tutorial".

This has worked pretty well, as the labels seem to fit most requests and I'm able to add them easily when a new Pivotal issue is created. It also helps me tackle these issues in bulk more easily. So, for example, one month I made a point of addressing all "Update" stories in order to try to get our documentation up to date with the latest release (I didn't make it all the way through, but I made a big dent!).

A few stories in the Pivotal Docs project


To help with planning, I devised a system for estimating the work required for our documentation and tutorials stories. Here's the current version:

  • 0 points - No change needed (e.g., duplicate or no longer applicable)
  • 1 point - Typo or minor wording change
  • 2 points - Updating or adding a screen shot, adding a new section to a document or a major re-write of one or more sections of a document
  • 3 points - Creation of a new article or video

There is a big jump between 2 and 3 points (writing a long article or creating a video can take a couple of days), so it's not exactly a linear scale, but it's simple and clear enough to be useful.

New additions

A new writing tool

One of the frustrating things for me when I started writing new documentation was just how long it took. For a simple document it often took a full day. One of the reasons is that our documentation is written in HTML (which is ok, although it adds some time) in a web-based tool (which makes iterations and drafts a bit challenging) and often requires screenshots (which can be a pain to create and upload).

What I really craved was one tool for everything, preferably that could work offline. After a lot of research, I settled on ScreenSteps Desktop, a tool for writing help guides that has built-in image capture. This was the killer feature for me. It can also automatically resize images to a set width to fit our web template. This saves me from having to edit them after I've captured them. And it outputs HTML with the ability to customize the output template with variables so that it generates the exact HTML that I needed to paste into Desk. My edits to the default template included removing the header and footer, mapping to the correct images directory, and adding specific CSS class names that we use on our site.

Our ScreenSteps HTML template, stripped down to meet our needs (click to see more of it)

I haven't used it for our main documentation yet, but it worked great for our "How-To" guides, which are heavy on images.

The process of publishing images also got easier when we moved to using GitHub to manage uploading our images, meaning that I could drag and drop them from my computer rather than using FTP.

A Style Guide for docs

Finally, we wrote a style guide for our documentation (although I haven't gone through the process of updating our old docs with it). It covers topics like rules for HTML and how text should be capitalized and formatted.

A work in progress...

One of the big things I was hired to do was improve our documentation and I'm pleased with the new content and processes we've added in the the last year. The process is a lot smoother than when I started and I'm hopeful that our content will take another big leap forward in 2014.

Still, I know that as a UX designer turned Doc writer I have a lot of room to grow, so I'm focusing on improving my abilities. Although I've been struck by the many similarities between UX design work and writing documentation. For instance, the process of creating something based on a specific need, giving an orderly structure to it and then refining and polishing it seems to activate the same neurons as designing a UI for me.

It also has many of the same challenges as my UX roles. Much like coming into a company as a new designer, I inherited a "product" (our support site), which had existing content and an underlying technology platform, both of which were limiting in some way. There is a significant cost to shifts in either that can outweigh their advantages. (We have researched other documentation platforms but haven't found one that meets our needs much better than what we have, so I'd love to hear what works for others.)

Fortunately, I've had help throughout the year. I adopted the good practices that had been established when I arrived. And I started paying a lot more attention to other support websites and made an effort to understand how they were designed. I also attended the Write The Docs conference last year, where I connected with other doc writers and learned about the resources and tools that they use.

I'm still learning though, so I welcome your advice or feedback in the comments!

Improving the Experience of Our Support Website

contact us

At Balsamiq we've always prided ourselves on our customer service. We have real live humans who stand by the phone and love hearing it ring. And we're blazing fast with email support by providing coverage from our U.S. team during our working hours and passing it off to our European team during theirs.

We also rely heavily on our web support channel, i.e., our support website (support.balsamiq.com). This site serves as our repository for product documentation and FAQs, helping people learn the product and get help if they run into trouble. Our support site is very important not only for customers wanting to get answers, but for our support staff, who can direct people to specific articles that can answer their questions.

In 2013, we identified several touch points in our customer journey that we wanted to improve. Support was a primary focus, being an aspect of the company's service that customers can repeatedly return to. A little back story describing the evolution of our support site may help understand what we hoped to improve.

When Balsamiq started, our documentation was modestly maintained on our servers (a single page per product) and we responded to support primarily using Gmail and GetSatisfaction. As the company and customer count grew, we grew our support team. In 2012 we started using Desk.com to manage our support system, from email management to publishing our documentation.

We shipped a very basic site with a searchable set of articles using Desk's base templates. While we continued to write support articles and improve how we responded using the email management capabilities of Desk, the support site was largely unchanged. The questions and feedback we got over that first year helped us become aware of its limitations, and we started to describe the problems internally.

The predominant issue had to do with difficulty locating content. From our perspective we also identified problems connecting related content, keeping media up to date, and knowing if users were getting the answers they were looking for.

This was a re-alignment and not a redesign. We set out to improve the site, focusing on aligning the organization of content and the layout of entry pages to address the findability problems, and gardening the current content to reflect user needs.

A new look + better organization

Here's a list of the most noticeable changes to our support site, although there were many other, smaller changes we made to both our processes and our site.

Updates to our support home page

We wrote up requirements and started wireframing a rough idea that we could use to discuss the problem and explore solutions. We iterated over it a few times until we had a basic understanding and agreement on the direction we wanted to take, and immediately started front end development. We like to make refinements in further iterations in code.

This screenshot shows our initial wireframe for the support home page.

Rather than just showing the first 10 articles in each category we wanted to encourage visitors to either search for what they are looking for or choose a category to drill down into for a more approachable index page for that category. This cut down greatly the amount of text on the page and provided better entry points to a refined search. Also, by looking through our logs, we could pick out some of the most popular search terms and place them next to the search box, helping people who didn't necessarily know how to describe what they were looking for. Finally, increased use of icons and images would differentiate the categories and other link targets better.

Here you can see a comparison of the original support site's main page with the redesigned version.

Better, no?

Better sidebar navigation

Our sidebar (the grey navigation bar to the right on our individual articles) now links to headings within the page so that you can get an overview of the article you're reading without having to scroll all the way through to see if it contains the content you're looking for. We've also tried to save some time and effort by providing links to some related articles below that in case the page you're on doesn't answer your question or you want more information.

This screenshot shows some of the navigation changes to our sub-pages, as well as updates to our tutorials (discussed below).

What's new?

More focus on tutorials

We got feedback last year saying that many of our articles were too wordy and too focused on describing features rather than on how to actually do stuff with our products. So, we made a concerted effort to step things up in the tutorials department. Here are some of the changes we've made.

A new index page for tutorials

We started by creating a new home page for our tutorials. It's grouped into categories for beginners, intermediate users, and people who want to do more with our products once they've learned how to use them.

We also got feedback from people who said that they just wanted to see the videos, so we've labeled the tutorials that contain videos as well as consolidating all of them into one playlist that's viewable at the bottom of the new index page.

"How-to" guides

We also experimented with some different kinds of tutorials. Some people said that many of our articles were too general or that they didn't have many pictures or enough guidance. So, we took some of our most frequently asked "how do I...?" questions and created a few detailed, step-by-step guides showing these processes each step of the way. Our guides on how to create a symbol and how to download from Mockups To Go, for example.

More "Tips and tricks" videos

We describe Balsamiq Mockups as "Excruciatingly simple. Filled with hidden powers." The goal of the videos we've added recently has been to reveal some of those hidden powers by showing how you can do things with Mockups that you may not have thought were possible and/or easily accomplished. We relied on our own Mockups experience as well as examples from our customers to create a few short videos, such as "How to Use Show / Hide Markup for Layering" and "How to Create Multiple Header Rows in a Data Grid" that might make you say, "I didn't know you could do that with Balsamiq Mockups!" We hope to create more in the coming year.

Here's an example of one of them:

Looking ahead / our hopes for 2014

Here's a quick list of some things we'd like to add in the next year:

  1. Better, clearer docs, more tailored to specific needs
  2. Better metrics for tracking the usefulness of our articles
  3. A more structured course for learning Mockups
  4. Tagging or labeling for better cross-referencing of articles
  5. Applying the editorial style guide that we finally got around to creating to all of our old articles

How are we doing? What would you like to see more or less of? Have any tips for us? If so, leave a comment below or email us at support@balsamiq.com. We're eager to get better!

— Leon and Mike

Next Page »