Balsamiq

Balsamiq Mockups Online Help

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. 🙂

---