Already have a monthly subscription for our cloud-based web app?
Log In to myBalsamiq
Lost your Mockups key?
Retrieve Your License
Part of our mission at Balsamiq is to spread the knowledge of User Experience. Recently we have been tweeting more about it (both at our @balsamiq and @uxapprentice accounts), sharing useful resources via our social channels, writing blog posts and interviewing Balsamiq Champions to inspire you with their awesome work.
Today we're adding another piece to the puzzle.
In 2013, we worked on a project with Theresa Neil. She has a depth of teaching experience as an author and as a consultant who educates companies about UX Design. Together we developed a learning resource to help people who want to begin a learning path in User Experience.
This led to UX Apprentice, a web site that covers some of the basics of the practice, teaches you the basics with an easy process to follow, and provides links for digging deeper and perfecting the craft.
Making UX Apprentice available in multiple languages is a natural next step to help people all over the world take advantage of it. We even heard that the site is being used in schools to teach the basics UX, we want to make sure that all kids around the world can understand it fully!
We have translated UX Apprentice into Portuguese - with the help of Thiago Tomasi - and Italian - with the help of my degree in Italian Linguistics ;).
Click on the world icon at UXApprentice.com and you'll find 3 languages under the World icon: English, Italiano, and Português.
German, Spanish and Persian are already on their way!
We are looking for volunteers to translate the UX Apprentice in as many languages as possible.
If you want to be part of this UX educational project, just follow these simple instructions.
It's not a huge amount of effort, and you'll truly be making a difference in helping rid the world of bad software. You'll probably learn a thing or two in the process, and will forever be enshrined on the UX Apprentice Credits page. :)
We're looking forward to working with you!
You land on one of those "12 examples of beautiful interface design" articles and admire the screens of polished wireframes. In some photos you see monitors shot at an angle with screens askew, receding into the distance, and a slight vignette burning away the edges. Perhaps you think to yourself, "Maybe I should make my UI design look like that?"
It's easy to get seduced by these creatively presented shots of user interface deliverables. If making clean wireframes does cross your mind, we think you can do so successfully provided that you don't put aesthetics before the goals and purpose of wireframing. There are valid reasons for not using sketchy wireframes. Sometimes low-fi aesthetics gets in the way, whether its due to the baggage of hand-drawn fonts or confusion over sketchy lines. That's why we made the wireframe skin, and its minimalist aesthetic is right for these occasions.
We advise caution. I know, I may be preaching to the choir, but humor me. It bears repeating because people new to wireframes may not know this.
Wireframing is not meant to be doing visual design, and this is why people make their wireframes as devoid of designed elements as possible.
Overly "designed" wireframes may ultimately lead to having to provide disclaimers as you deliver them. So get comfortable with this phrase: "Disclaimer: This is a wireframe and is not meant to convey visual design." You may even put that in your wireframes. We've seen that done plenty of times.
Stepping off the soapbox. Let's get started. We'll be working with Balsamiq Mockups Version 3.
Just because you're working on wireframes and not visual design, doesn't mean you have to throw your design sensibilities out the window. If you're already steeped in design principles, it'd be hard to make a wireframe without that knowledge influencing where and how you place elements on the canvas.
Let's start with a few examples of what you might do with wireframes and basic diagrams.
You can download all of these examples in this Project file.
These examples eschew sketchiness and the hand drawn look. They're mostly grayscale with an accent color. There's obviously a little bit of alignment, arrangement, hierarchy, and repetition there.
The features in Balsamiq Mockups for non-sketchy aesthetics are easily accessible once you know what to look for. Let's dig into how to create wireframes like this.
We start by switching to the Wireframe skin. To do this, select the Project Information panel from the menu, "View > Project Information" or by pressing CTRL+, on Windows or CMD+, on the Mac.
At the bottom of the panel, select Wireframe Skin and choose a different font. A solid sans-serif font like Helvetica works well on the Mac, for instance.
Flat design is a nice trend for people who do wireframes because our work has traditionally been devoid of surface decoration. If we look closer at how that first wireframe is created above, we see how the shape control and some subtle use of color can go a long way in organizing elements and suggesting hierarchy.
Here are some design principles and techniques that help when doing minimalist wireframes.
Keep colors at a minimum. Consider using flat areas of color rather than boxing everything and putting noisy borders adjacent to each other. Stick to a monochromatic palette of mostly white, black and grays with an accent color.
Use Contrast Wisely
Use contrasting font sizes to denote hierarchy. When elements are distracting, consider reducing contrast in visual elements to reduce their importance. Elements like separators, HRs and border boxes are good examples that sometimes draw attention away from more important parts.
Use Proximity and Alignment for Visual Organization
You may not need to box every element and add a strong HR between everything. As above, use contrasting font sizes or color. Put like things close together and add white space to separate groups. As a general rule, look to align almost everything with something else in the canvas.
Employ Functional White Space
Again this goes with the previous technique. White space helps to separate, to help direct the eye, to suggest the order of scanning and reading the page, and to help make text legible. The eyes like to have space to rest as they move between blobs of objects.
To get a little meta, I made a wireframe of our wireframing tool in order to show you these tips. (Hopefully that recursion doesn't make your head explode.)
The most common control you'll use for simply blocking out areas with solid grays will be the Rectangle. But also consider the Shape control as one of your tools for polished wireframes.
The Shape control is a Swiss Army knife of an object. It was originally meant for quick and dirty flow diagramming, but in reality it's more often put to use for general-purposes. We'll look at some examples, but first let's discuss how shapes can be useful.
Consider how drawings are made to understand how to use the Shape Control. This fun video shows how manga illustrator Mark Crilley uses the basic shapes of circles, triangles, arcs and straight lines to build up the anatomy of a face.
The good news is that in Mockups you don't have to know how to draw a circle. You can, however, layer shapes in a similar way to make other objects. Making design elements with the shape control is something that many experienced Balsamiq users do when they want to create an object that doesn't exist, or make a control that looks different from what we provide in the UI Library.
Let's look at an example created by Balsamiq user Georges Raad. Georges created a great symbol library using the Shape control extensively to make some interesting elements like ribbons. Let's break down his controls to see how he made them.
The basic idea is to look at the overall form of a thing, then try to break it down into simpler geometric shapes. This is what Mark Crilley demonstrates above when he draws a face. You can do lots of interesting things with just the Shape control. Here are just a few examples of the kind of thing we see people doing using the simple technique of layering shapes that we show above.
[Common Controls by Georges Raad; Doughnut Chart by Henning; Apple Watch by Ben Norris, Map Controls by Michael Gaigg; Margarita Recipe by Jim; Bootstrap, TR808, TV Remote, and Moockups Cow by me]
You can see more useful examples of what people have built by getting creative with shapes at Mockups to Go.
Most people who use Balsamiq don't have to create polished wireframes. Low fidelity keeps the conversation centered on figuring out the problem and communicating the functional solution.
A wireframes vs. high-fidelity prototype vs. visual design debate is not what we're after here. We're interested in giving suggestions for making clean, minimalist wireframes if you must, whether it be for client presentation or other reasons. I admit that we occasionally do this at Balsamiq when we're working on an existing feature, or if I'm going to be doing visual design work using the design language we're already using in our products.
As you make polished wireframes, the slope becomes slippery as visual design decisions creep in. Be sure to stick to the same rules you've always known for wireframing with Balsamiq.
A last reminder is not to let aesthetics get in the way of rapid idea generation. If it does, maybe you should be sticking to the Sketch skin. For the majority of our customers and for us, it is still a tried and true way of focusing on what's important.
There's no single "right way" to wireframe. What you should deliver depends on your circumstances. In the end, ask yourself, "Does this help or hurt me in trying to explore, find, and communicate the problem and solution I'm presented with?" If it helps, use it, but do it carefully. Hopefully this gives you another way to go out and make something awesome.
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.
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.
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:
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.
What things should not change on the surface?
What things should not change about the experience?
What things are so effective that they create “Flow” when using the app?
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:
And, with that, we moved on to…
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.
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:
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?
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.
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. ;-)
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.
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:
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
One of the most popular things about our little tool is how quickly you can create meaningful wireframes with it.
But there are ways to go even faster with Mockups. Symbols, for example. Symbols let you create reusable common elements across different mockups. Useful, right?
Another way to speed up the process of creating your wireframes is to browse mockups, symbols and UI controls from our community on Mockups To Go. They are free and ready for you! You can contribute, too. :) Find more information here.
If you are looking for some UI Controls that aren't included in the standard set of Mockups controls, here are some symbols that could save you time.
...who doesn't need a Captcha??
Form Captcha inspired by Google Keyword Tool. Contributed by Dima Semensky.
Download Image and BMML here
No need to recreate these ever again!
Password strength indicator controls. Contributed by Alain.
Download Image and BMML here
A calendar with a monthly view, ready to use in a sidebar or wherever you need it to be shown.
Contributed by Piet.
Download Image and BMML here
If you haven't used Mockups To Go before, read these instructions first. Then find the controls above and more on Mockups To Go!
Over time, I have learned to consider the first wireframes of any new idea to be "version 3", meaning that, because of how our brain works, we usually tend to put way too many details in them.
So, once the wireframes are done, I scale them back once (version 2), and then do it again, to get to what should be released in version 1.
I wrote about this little trick as part of a Reddit "Ask Me Anything" session I did last year, and forgot all about it...until I received a CRAZY email a few days ago.
Here it is in all its glory:
From: Chase Reeves <firstname.lastname@example.org>
Date: Tue, Dec 16, 2014 at 5:42 PM
Subject: You inspired this quick post (+ a few gifs)
There was a bit in your Reddit AMA where I was, all, like this:
Cuz, before that bit my ideas were, like, this:
I couldn't nail the MVP, just wasn't capable:
Then you were, all, like this:
And now i'm, all, this and this:
So I wrote up this post.
Been sitting on this one since all the way back to your reddit AMA.
Big fan, fellow speaker and bootstrapper.
Cheers, Peldi! You're a magic man.
Chase, you made my day. :)
The post Chase wrote is really interesting, it elaborates on the Version 3 idea quite nicely. Check it out, and check out his startup Fizzle, too!
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.
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.
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.
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.
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).
(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.
You can also extend your pattern library by creating your own Balsamiq Mockups controls as Symbols to map to other components in your library.
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).
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.
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:
Some resources to help you develop your own pattern library:
We created a tutorial to give you some ideas for how to create project templates that contain elements you commonly use in your projects.
Along with this tutorial, we created two example templates.
The UX Template is designed for people working on UX Design projects who typically need to present a polished deck to clients. Here's a preview of what you'll find in this template.
The Bootstrap Template is designed for people who know they're going to be using Bootstrap, and want to use the text elements, and components common to the Bootstrap framework. Here's a preview of what you'll find in this template:
You'll find more information, including videos for how to get started in the tutorial.
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.
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:
ALL THE CONTROLS! (download this file)
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:
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!
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.
Documentation updates can be prompted by several actions. Here are the primary triggers:
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:
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.
To stay in the loop I also monitor the Support HipChat room so I that can see what people are having trouble with.
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:
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!).
To help with planning, I devised a system for estimating the work required for our documentation and tutorials stories. Here's the current version:
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 do be useful.
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.
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.
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.
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!
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.
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.
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.
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).
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.
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.
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.
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:
Here's a quick list of some things we'd like to add in the next year:
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 email@example.com. We're eager to get better!
— Leon and Mike
The UX Blog is where we talk about the user experience of our products, showing you what we're thinking and how we're evolving. We talk with you about your UX needs, and share tips and tricks to help you use Mockups better.
Live outside the Americas? Use our European shop.