How to write good help pages for rich web based application screens?

Question

I'm working on writing help pages for a web based application. What tools, resources, and/or best practices are there to write help pages that are geared towards individual pages of a rich web application with a lot of functionality?

The help system will have a button on each screen that help is available for, when the user clicks on that button a new browser window with its toolbar stripped off will popup to give help documentation for that page.

These help pages are very common in Windows and shrink wrapped software, but I can't remember seeing any web applications that use them, Gmail, Google Calendar, and google docs have well written documentation, but I actually think they don't do a good job of giving you help documentation that is relevant to the screen you are looking at.

Answer 1

Have non programmers (better non techies at all) use your application, sit close to them and write down everything they don't get almost immediatly, that needs a help page.

Google for his gmail has the help page, where the user goes with a clear problem in mind to search for.

Answer 2

Most often users of help are relatively knowledgeable but don’t know how to complete a specific step of a task. They’ll turn to Help as a last resort after searching the UI itself for some clue on how to proceed. Your user wants an answer within 30 seconds and then get back to work. Thus your help for a specific page should be:

• Organized by task. List the tasks and subtasks that may be completed on the page and how to do them. You can also organize help by controls or content, but more often users will want to know “how to do X,” rather than “what does Y do.”

• Make Help page scannable so users can jump to the point in the task where they need help. Use headings, tables, and hierarchical layout. Put the most critical text in the first few words of a list item. Use bold print for key information inside blocks of text. Keep the Help page short. If there’s a lot the user can do on the application page, then have links in the Help page provide detailed information.

• Keep text short, concise, and to the point. Don’t over-explain or dwell on every-day use of the app. Assume users know the basics about using computers and the subject matter. Provide links for definitions, large examples, details, alternative methods, and full tutorials for those that need it.

• Provide more conceptual information than mechanical. Yes, say or show what button executes the feature, but if your UI is well designed, the button should be easy to find. Focus more on things the user can’t tell by looking at the UI, like how to choose the right parameter values, compare and contrast the cost and benefits of options, rules for formatting or processing data.

In addition to the above characteristics for individual help pages, consider the following:

• Have effective search able to handle synonyms and related words. If users don’t find their answer from Search, they tend assume the app can’t do what they want to do. Certainly every error message, every control label, and every parameter value you show users should be findable in Search.

• Don’t rely on Search. Every Help page should link to a single Help Home page with well-categorized task-centered links to all other aspects of help.

• Include a FAQ for common problems. Or better, consider re-designing your app so it doesn’t have common problems.

• Don’t have a Help page separate from your app but have Help integrated in your app with in-line help or balloon help.

The webzine UXMatters has had a number of good articles on Help:

http://dev.uxmatters.com/MT/archives/000170.php

http://www.uxmatters.com/MT/archives/000190.php

http://www.uxmatters.com/MT/archives/000222.php

http://www.uxmatters.com/MT/archives/000242.php

http://www.uxmatters.com/mt/archives/2009/04/searching-help-dont-even-go-there.php

Answer 3

This stuff was all hashed out a decade ago in the WinHelp world; there are many excellent books on the topic, if you can still find a used copy. Probably the best book for help was Developing Online Help by Boggan/Farkas/Welinske. Although the parts specifically about WinHelp are not of any use, the parts about writing and organizing help topics in general are excellent.