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

We'll send you just one email a month and share a ton of information that you'll get before everyone else. More info about the newsletter here.

We'll never share your email address or spam you.

Leave a Comment

Your email is never published nor shared.

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?