Using Balsamiq in specification documents

I’ve found using Balsamiq to demonstrate a walk-through to a customer using the presentation mode to be really useful. However, I wondered if and how people were actually using the materials created in final specification documents.

  • Do you extract screens and then embed them in Word documents? How are people embedding them? As images? SVGs?
  • Extract individual page elements, embed them and describe them?
  • Embed the documentation into the Balsalmiq project itself using the notes and then print the project out?
  • Export the whole project as a PDF and the cross reference from the specification document to pages in the project PDF?

My preferable and most frequent way is:

  1. Create Google Document
  2. Insert images from Balsamiq
  3. Describe the solutions (if it’s not obvious from the images and the notes in the images)
  4. Share the document with a customer

I embed the images using CTRL+ SHIFT + C shortcut, which copies to clipboard the selected objects from mockup. Sometimes though I use external print screen software to get some part of the mockup.

PDF or BMPR (Balsamic’s native format) are not so good as a both-side communication tools. And the communication is the most important part of the process.

Google Docs is a good way for communication, both a client and me are sure of using the actual version. It supports versioning, as well. A client either use comments, or edit the document. I’ve attached a screenshot as an example. You can see a huge comments there…)

Recent Balsamiq versions support commenting, as well, but from my experience, documents are more convenient way to communicate. Comments in Balsamiq are good for short notes.

Please feel free to ask if you need more info. Also would like to know how the other designers work with specs.


I follow the exact process that Alexey_Kolchenko described. It works really well … except when I have to make a change to the mockups. Then, I need to go to Balsamiq, make the change, do the Ctrl+Shift+C shortcut and replace the image. That’s generally not a big deal. However, if the change is something “global” (like a symbol), I have to go back through every image and replace it. In spec documents that are 100s of pages, that is a real time suck!

I have looked for a method/tool that would embed the mockup (with a link to its source) so that changes would be reflected automatically but I’ve never been able to find one. If anyone knows of a solution for that problem, I’d love to hear it!

One other issue with the image-in-Google-doc route occurs when the mockup is long. In order to get it to fit on the printed page, it has to be resized, often to something barely legible. I’d love to have the option to make the embedded image a thumbnail linked to a larger view.

Hint to the Balsamiq developers: A product that does just that would be AMAZING!

1 Like

Seems like a good idea to me, @DanniB. I will chat with the dev team about it and see if it’s possible. :slight_smile:

Hey @DanniB,

Some more details on my workflow:

  1. To cope with long images, I use landscape orientation and the appropriate page size to keep the mockup width at 100%. The issue with the length is solved just by disabling Print layout. And I include the message in the top of the doc! You can try it in the attached doc, I’ve placed a long image there (760×1292) :wink:

  2. I almost never update the images, my way is moving the old ones to the Archive section in the bottom of the document. I insert the new images and description of the new solution in the right place. This is also old-fashioned version-history tool, which contains all the valuable comments from a customer on the previous iteration, so I can refer to these easily

  3. I usually create the separate doc per epic, so each the doc is quite small/medium. The separate doc contains the list and the links for the dedicated documents

Please look at a kind of template I use in Google Doc.

PS. Google Doc has the feature of replacing images. Probably, not the best solution though. As for me, I prefer to copy and paste the selected mockups with hotkey CTRL + SHIFT + C. It’s lightning fast :wink:

I have been using Word documents (although I will look at Google Docs next time). All my wireframes the same fixed width, but if they are too long for the page, I sliced them up using an image editing tool. I then use page breaks to make sure that the images don’t get pushed around too much. It does mean that there is a bit of white space at the the end of a section but prints perfectly.

1 Like

Just chiming in based on my experiences in the field.

Exported images embedded into Word/Google Docs is the most traditional/common way of doing it. The advantage of this is that it fits into existing workflows. The downside, as you mentioned, is that it can be a pain to update the images.

Here are a few alternatives that I’ve seen.

  1. Some companies already use Atlassian Confluence wiki for everything internal, including specification documents. They can take advantage of the Balsamiq plugin to edit and update mockups directly in the document. See our docs for more info.

  2. We also offer Google Docs integration with our Balsamiq for Google Drive plugin. It works similar to the Confluence plugin, but for Google Docs. It’s pretty neat. Read more about it here -

Lastly, for people who use agile user stories instead of specification documents, here’s a short article I wrote about using wireframes with user stories - What I used to do is tell the developers that the story text (e.g., acceptance criteria) always trumps the wireframe. So, if there was some minor detail that I needed to update, I’d just leave the old wireframe in there and update the text to say what the correct label, icon, etc. should be instead. (For bigger changes, I’d still update the wireframe though.)

Hope this helps!

1 Like