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.

    Volunteer Opportunities for UX Designers or Developers

    code-for-americaPhoto Credits: Code for America

    We spend years developing skills and craft to further our careers. That experience becomes a valuable resource that may be put to good work in the form of volunteer time or pro-bono work for nonprofit organizations.

    Individually, some of us get opportunities to help others by word of mouth referrals. If you're a UX designer or developer looking for ways to provide your expertise to organizations needing assistance, or a nonprofit in need of some design time, try some of these sites that may help you find the right match.


    Conferences focussed on matching design/development expertise with nonprofits are a great way to see who's doing what, and talk to a lot of people in one place. There are a handful of well-known events that draw a diverse crowd.

    The Feast, for example, inspires with the stories of organizations successfully doing work to improve the world, and then puts immensely talented tech people in the same room with organizations focussed on this meaningful work.

    The Nonprofit Technology Conference (NTC) is a conference focussed on Tech projects in the nonprofit sector. The event brings together a large number of organizations in its network, to foster sharing information and collaboration. Networking events at the conference, we're told, are one of the best ways to find out more about a lot of organizations in the nonprofit sector doing work that may interest you.

    Searching for Volunteering Opportunities

    If you're just starting to do your research about volunteer opportunities, or simply know what type of organizations and work you'd like to contribute to, these sites feature events or listings of volunteer opportunities.

    • Code for America - Organizes and builds open source software to improve government services using volunteers. One page provides specific issues that can be worked on.
    • Community Corps - A skills-based volunteering program that matches technology professionals with schools and nonprofits. Organizations request volunteers and the Community Corps lets volunteers search for specific opportunities related to skill. Mostly technical, but there are some categories like website review, which would be relevant for people who do usability evaluations.
    • Geeklist Hack4Good - Organizes hackathons to build solutions to humanity’s greatest problems.
    • Hackathon for Social Good - Organizes hackathons to build web and mobile applications for nonprofits.
    • Volunteer Match - Volunteering site that lets volunteers search for opportunities by cause and locale. Doesn’t provide any match of ability to need.

    If you know of any other resource that would be helpful to include in this list, please email us at support@balsamiq.com! We'll be maintaining an ongoing list of resources for volunteering and finding volunteers for nonprofit work.

      Wireframes: A New Tool for Marketers and Content Writers

      Let's imagine.

      The Marketing Department just created the ultimate inbound strategy; the plan has been handed off, and now it's the copywriter's, designer's, and developer's turn to make their individual contributions and get the best results.

      But, how can each member of the team know what's needed to achieve those results? More specifically: How long should the copy be? What goes above the fold? How can we make it more mobile-friendly? The list goes on.

      Teams need to put in place a common framework to succeed. One that enables an appropriate information interplay where structure, content and design work together to achieve the expected goals.

      Start with wireframes


      Our designer and writer, Leon Barnard, in his latest post for the Atlassian Blogs, addresses this issue and explains how teams can benefit from using wireframing as a common framework to improve collaboration and bridge the gap between content and design. He suggests a couple of techniques:

      1. Wireframing to avoid the design gap: to help designers and writers communicate with each other and work in harmony.
      2. Wireframing to get better feedback: for rapid idea exploration and iteration by trying out visual variations, getting feedback on them, and then make changes.

      Adopting visual tools to improve communication is no longer exclusive to designers. Marketing and content professionals are starting to introduce these techniques to enhance their workflows and share their work. In the case of web copywriter Kate Toon, laying out the copy and creating wireframes for clients “transforms the way they see the copywriting process.”

      Still, wireframing is a new concept for many. To help get a better grasp on it, check Leon’s interview for the Inbound Unboxed Podcast where he gives a deeper look at the basics, best practices, tools and the benefits for marketing and content professionals.


      Communication and collaboration are essential for our projects to deliver a delightful user experience and be successful. Having the right processes and tools in place can result in better products and more efficient, in-sync teams.

      If you’d like to give wireframing a try, we've prepared a quick guide to help you choose the right tool. You can also try Balsamiq Mockups for free on our website, or download a free trial. If you need help, you can reach us in many different ways. We have extensive docs, tutorials, and awesome customer service.

        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!

          Staying Fresh with Good Old HTML and CSS

          I know web design

          As the internet keeps evolving at staggering speed, new tools are released constantly, and employers are always looking for the most experienced players. Designers seem to have no choice but to struggle with what to learn next.

          Fortunately, our own Leon Barnard has offered his help on how to survive and succeed in this seemingly ever-changing industry. In his most recent article for the Treehouse Blog, he suggests we shouldn't underestimate plain old HTML and CSS to stay at the leading edge, and he gives us 5 reasons why:

          1. HTML and CSS are design tools
          2. HTML is what the browser knows
          3. CSS3 is replacing JavaScript as the language of animation on the Web
          4. Wireframes with CSS are better than a Photoshop Mockup
          5. At the very least, you can customize a web framework

          Agree? Disagree? Would you add anything to this list? How do you stay current on your career? Share with us in the comments.

          For a deep dive into Leon’s advice, we invite you to read the full article.

          Jessica for the Balsamiq Team

            Tips for Creating Great Screencast Recordings

            As a UX team, we're always trying to improve the work we do to support our customers. Video has become a big part of that.

            Video is a resource we provide in Tech Support and in our regular release announcements. Screencasting technique is one thing we continually improve, so when Leon and I were recently asked to create online courses on Skillshare and Udemy, we took the opportunity to go a little deeper into expanding our recording knowledge so we could deliver higher quality video.

            Here's an example of a video we recently produced, with help from Skillshare.

            In this article, I'll share tips for getting the best out of your screencasts. Many of the tips are aimed at those looking to record multi-video courses on a Mac, but you can apply most of the advice to shorter recordings and on Windows. I've gathered these pointers from articles over the years, as well as from the great support team at Skillshare.

            Screencasting for courses with multiple lessons was something that was new to me. We typically do short recordings for intro videos, demos, and tutorials. They're typically a single video and are relatively short. Often times they're designed to be digestible in under a few minutes. A class was a different kind of challenge, as its goals are to teach a new user a lot over the course of many different videos organized around building up skills they need to produce the desired outcome—create a product's user interface deliverable.

            I got a lot of good advice from the team at Skillshare about how to approach the task, most of which I applied in the recordings. If you're interested in screencasting for online courses, they offer a free class, "Teach a Skillshare Class: Screencasting." It's very useful if your goal is to record an online course for their platform.

            Now, on to the tips!

            Organizing your Content

            1) Start with an outline and break it down into smaller pieces.

            The first task at the outset is to describe what the product is. I defined who my audience is, and what I expect them to get out of the course. This started as a discussion about product development and trying to understand how the video could frame the course in terms of real needs. This turned into the course description, which became the mission for the video.

            Here's the description I used for the course.

            Learn how to successfully create wireframes for early stage product design with interaction designer Michael Angeles, as he shows how to use Balsamiq Mockups to design interfaces with product teams. Balsamiq runs on the desktop or in a web app, and also as a plugin for Google Drive, Confluence and JIRA.

            In this 51 minute class, you'll see how concept selection can be tackled with low-fidelity wireframes, learn to create rough sketches to explore ideas, and then transform them into interaction design solutions that can be refined quickly, and polished for presentation. The class is perfect for product managers, developers, and those new to designing with wireframes. No prior knowledge or experience with interface design is required. By the end, you'll be able to present wireframes for a finished product idea and demonstrate a clickable prototype.

            After nailing down this summary, I started with Skillshare's template, breaking down what I wanted to teach in the course into these main sections: Intro, Key Concepts, Project, Summary. Sections can have multiple units or videos.

            The idea is to start with the broad sections that you want to cover, and then work from that to define what you'll show in each section. My outline consisted of an introductory lesson at the beginning, a short summary at the end, and in the middle were 2 large sections for what I intended to teach. As I worked on an outline, I made guesses at how long it would take to cover a part. I was able to see where I could break the topics up into smaller videos from this, and broke parts up when my guesstimate was longer than 7 minutes.

            I then added more detailed notes to my outline about key things I wanted to show and say, and in some cases, intro/summary messages that I thought would help. More on that in the tips.

            As with designing a product, organizing in the planning phase also provided a very good opportunity to see what could be eliminated and edited down.

            2) Introduce the topic and set expectations.

            Tell the audience a few key things about the video.

            • Who is the course designed for? For example, talk about roles, types of needs of the person who will learn from this instruction, etc.
            • What can viewers expect to learn? If this is for a course, talk about what skills they'll acquire, what types of things they'll be able to create (show examples!).
            • How long will the course take?

            3) Do a short intro in each section.

            If this is a multi-video course, a sentence or two to introduce each video is helpful. You can use a title slide along with a little overview of the topic, feature, procedure, etc. that you plan to show.

            4) Add transitions at the end of each unit.

            Transitions are short summaries to remind what was covered and introduce what's next. This was a great tip from Skillshare and it's something you may not notice when you take online courses, but it really helps to cement what the watcher just viewed into their mind, and give them a sense of continuity through the process.

            For the wireframing course, I was trying to establish a process or way of thinking about discrete tasks, and how to get from one task to the next.

            5) Vary the video content.

            This was another great Skillshare tip. Their teacher's outline suggests using different types of video styles throughout your recordings for a course. Anything you can do to mix it up makes it feel more engaging.

            For instance, you can show some video where you're directly talking to the camera. Other times, you'll talk over demos. You can also change the pace now and then. You could go slow after a section when the pace has been very packed with information. Where a natural break or change in topic occurs can be a good place to insert a pace-change.

            6) Don't rush through the screen recordings.

            The one regret that I have is that I may have covered too much and went too fast in parts of my course. If you find that you're having to rush to complete recordings, reduce what you're going to cover, or break it up into even more smaller pieces so you can take your time. If people are using your video to learn something completely new, they'll want you to go slow enough for them to see what you're doing and then try on their own.

            Video Recording

            1) Choosing screen recording software.

            We use a few different tools for recording the screen on our Macs. The simplest tool is Quicktime, but editing is limited with that tool, so you won't be able to easily add titles, transitions, and do complex editing. We tend to use Screenflow ($99) because it gives us some easy to use editing tools for these needs.

            2) Set up your screen.

            What screen resolution do you plan to record? For HD video, you want to record at a 16:9 aspect ratio. Aspect ratio is the proportion of width to height. Making sure your video is recorded at the right HD aspect ratio will prevent having pillar boxes, the black bars that are shown on the sides of video if it doesn't fit into an HD-proportioned video player.

            A common video resolution is 720p (1,280px wide × 720px tall). I created a template file to re-use when starting each video. Now to make things easier, you can set your computer display resolution.

            On a Mac you'll go to System Preferences > Display. You want to select the "Scaled" option. You can choose any of the 16:9 options that you see. I record our video at 1280 x 720 and set my display resolution to match so that the graphics are sharp. On my 13" Macbook retina screen, I choose the closest scaled option of 1280 x 800px This means that the bottom 80px of my recording may be cropped, so that's something to be aware of as you're recording.

            3) Create a template.

            Once I have my display set, I create a new document in my Screenflow software and set the size of the recording to 1280x720px. I save that to use as a template. Later I can set the defaults for elements I'll re-use, like callouts.

            4) Prepare your desktop.

            Turn off notifications. On a Mac, you can CMD click the Notifications icon in the upper right of your menubar.

            Clear off your desktop of files and icons that can be a distraction and pick a neutral desktop wallpaper. Alternatively, you can use a utility like Backdrop for the Mac that will hide the content of your desktop.

            If you have a crazy menubar, you may want to turn off some of the icons to remove distractions there. I use a utility called Bartender to just hide them under a hidden menubar.

            5) Use titles, text captions, and callouts.

            Title Screens are useful not only to introduce a video, but as text elements to introduce parts of a multi-part video series.

            Captions are useful when we want to re-iterate what's happening on the screen. This can a good idea for new users who aren't familiar with terminology you may be using, or if you just want to point out something of particular importance that you may be doing in your screencast. In our course, I also use this opportunity to show things like alternative ways of performing the task, like keyboard shortcuts or where to find the action in an alternate menu.

            6) To be consistent with visual elements, create a style guide.

            Create a style guide for yourself. We tend to go light on internal documentation, so a single page in a wiki that defines how we will use text elements, graphics, and transitions will goes a long way in ensuring some consistency in our presentation. We created a style guide for the following.

            For each type of graphic you'll use (titles, captions, and callouts) define the font, font weight, text color, background color and opacity, and position on the screen. For transitions, when changing from one clip to the next, we simply define the timing and easing we want the software to use when we add a transition.

            Audio Recording Tips

            1) Get clean audio in.

            Consider using a decent dynamic microphone. I used a Rode Podcaster USB Dynamic microphone ($230), and recorded directly into Screenflow for the course units, and into Logic Pro for the Intro video. iPhone headphones also work pretty well if you can't buy a USB mic. Just be sure to use a clip to isolate the mic so that it won't create noise by rubbing against your shirt.

            2) Reduce noise.

            A boom arm with a pop screen really works well to reduce noise, and anything you can do to remove background noise from the original recording will save you pain later. Ideally you can put a sign on the door when you're recording to reduce environmental noise, and turn off notifications on your phone, for instance. I use a Tonor Microphone Suspension Boom Scissor Arm Stand that attaches to my desk, and attach a Dragonpad pop filter to that. Runs about $24 for both.

            The boom arm helps to reduce noise that your mic might pick up from vibrations like tapping the table, for instance. It also makes the mic highly positionable.

            I position the microphone slightly at an angle below my mouth and talk outward to help reduce plosive sounds, which are already reduced by having the pop filter. Words starting with P and B sounds tend to pop and spike in your audio recording, which can be very loud to a listener, so the pop filter keeps them controlled.

            3) Record screen first, record voiceovers second.

            This helps to get fewer "ums" and "uhs." They can be very difficult to remove afterwards, so get good audio in. Record the screencast, watch the video once, do a voiceover recording in one take, starting over in parts when needed and edit.

            4) Warm up your voice.

            I learned this after hearing my voice and hating it. Voiceover tutorials talk about this a lot. I'll spare you the Googling and just tell you what I do.

            Drink water before voiceover recordings to avoid dry mouth sounds. Warm up your voice, lips and tongue before voiceover recordings by making faces to stretch out your mouth and utter a few "la la la la la's" out loud. You'll feel like a fool, but believe me, both things help.

            5) Clean up your audio.

            Ideally you're recording in a noise-free environment and isolating your mic from noise using gear like a boom stand. Background noise can be unavoidable, whether it's because you're recording in a city with street noise, or because you're recording at home like me and the sound of a computer fan or refrigerator kicks in. You can't prevent all that noise, so you might have to use some noise reduction, but aim for a clean background, and if you use background noise reduction, use it carefully. "Ducking" and the coming and going of noise can be a distraction.

            In the past, I've surrounded my mic inside a box to create a quick and dirty isolation shield to prevent noise. You can buy these as well. Search for "microphone acoustic enclosure" or "microphone isolation shield" if you want to go that route.

            If your voice recordings sound really dry and clean, it can also help to add some slight reverb, which will make your vocal recording sound like it's coming from inside a room where sound typically lingers slightly as it reflects in a room.

            In Screenflow I just select the audio inspector, check the Effect checkbox and add a little "Plate" reverb. For recording in Logic Pro X, I like the Library presets for Voice > Natural Vocal. I adjust the Plate Reverb send until it sounds natural without being over the top.


            Screencast recording can be a time consuming task if you do them often, but to us video demonstration is invaluable for classes, tutorials, and even in our case for feature announcements. Seeing and showing is usually better than simply telling, so we try to do both.

            We'll keep trying to improve how we do this to help our customers. Maybe this set of tips will help if anyone in our community is thinking about doing the same or looking for ways to improve their own screencasting technique. If you have tips you'd like to share, please add them to our comments below!

              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

                  Free Course on Rapid Wireframing with Balsamiq Mockups on Skillshare

                  We published a free course for Balsamiq users on Skillshare. The course, Rapid Wireframing: Finding the Right Product Design, is designed for those new to Balsamiq Mockups, but also features some demonstration of new features like Quick Draw and Alternates. If you're a veteran user, you may be interested in checking that out, and updating to the latest version to take advantage of these useful new ways of working on projects.

                  Here's a trailer to give you an idea of what to expect.

                  You'll learn how to successfully create wireframes for early stage product design as I show how to use Balsamiq Mockups to design interfaces with product teams, using the example requirements from UX Apprentice.

                  In the 51 minute course, you'll see how concept selection can be tackled with low-fidelity wireframes, learn to create rough sketches to explore ideas, and then transform them into interaction design solutions that can be refined quickly, and polished for presentation.

                  The class is perfect for product managers, developers, and those new to designing with wireframes. No prior knowledge or experience with interface design is required. By the end, you'll be able to present wireframes for a finished product idea and demonstrate a clickable prototype.

                  Start taking the free course at Skillshare now!

                    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!

                      Next Page »