Balsamiq

Toggle navigation

Balsamiq Mockups Online Help

· Posted by Peldi in Products · 2 Comments

I just completed the first draft of the Balsamiq Mockups Online Help documentation.

These are my beliefs about software documentation in our current state of technology:

  • software should be very simple and ideally require no documentation.
  • online help should be sprinkled around the app, in context. Read this article for what I mean.
  • very few people actually read the docs as if it was a book - note that this wasn't true 10 years ago, I used to love reading printed manuals. I believe some people still do read it top-to-bottom, so it's good to give some sort of narrative structure to your docs.
  • people only go to help when they have a problem, so you need to make it easy for them to find a solution. In other words, help should be more of a FAQ than anything else. To support this, I think all help should be on one single HTML page, which is easy to print, turn to PDF and most importantly a "Find in this page..." command (CTRL+F) will be effective on it.
  • a picture is worth 1000 words, especially when you're trying to explain something, so add as many screenshots as you can.
  • the docs should be a live document, always and continuously updated. That's why I don't embed the doc with the build but rather keep it in one location online. Also, FAQs should be incorporated in the docs over time.
  • you should support deep-linking to a section of the docs. This allows you to just send a very direct link in a support situation without having your user have to scroll down 3 or 5 pages, they're already confused as it is!
  • the docs should not be one-way nor they should be an end-point. It's likely that your users won't find their answer in the docs, so give them an easy path to a place where they can find an answer (like the forums) or ask a question. I use GetSatisfaction for both, and point to it right at the top of the docs. And if that doesn't work, I send them to the support page where they can email me or call me.
  • finally, the tone. You don't need to talk down to your users, they probably have been using a mouse and keyboard for years, and have dealt with harder software than yours (at least you should hope so!). Just imagine you're explaining your software to a peer.
  • Oh, and please oh please don't have any typos or misspellings, that just looks terrible.

Ok, after that last one I'd better go read it over again. 🙂

Peldi for the Balsamiq Team

Get the Inside Scoop!

Want to be part of the Balsamiq inner circle?
Want to know what we're up to before everyone else?

Subscribe to our monthly newsletter! See Past Issues.

Dazz Knowles
"Of all the e-mail newsletters I get, @balsamiq is the one I always read, they're brilliant!" - Dazz Knowles
Jérémie André
"Another great newsletter from @balsamiq!! 😁" - Jérémie André

Leave a Comment

Comments (2)

  1. Hi, Michael. This was fixed in the latest release.

    Support is all handled here:
    http://support.balsamiq.com

    Help for Mockups for Desktop is now found here:
    http://support.balsamiq.com/customer/portal/articles/127377

  2. I agree with all of this…..however, in the program itself, clicking Help > Online Help takes me to a 404 page.

    “…people only go to help when they have a problem, so you need to make it easy for them to find a solution….the docs should be a live document, always and continuously updated. That’s why I don’t embed the doc with the build but rather keep it in one location online….”

    I love the program, but where do I find online help these days?