What is the preferred way of creating a help section for applications?

Question

I'm wondering if there is a modern and preferred approach of the manual format from the standpoint of users. I thought about making a CHM file but my manager told me that feels very "Windows 98ish" and have asked me to look for alternative options.

The application I'm making is a small internal business app that will be used by maybe 15-20 people at most. The user can navigate in the program by clicking on the left-side tree menu which docks a window on the right side.

Here is a simple requirement: pressing F1 while having a menu opened should automatically open the relevant section in the help file.

Some considerations I thought about:

1) Create a PPT file->Convert to HTML->Open relevant page in a default browser

Pros: User has the option to use their favorite browser

Cons: Must validate that the page displays correctly in most browsers. Only works in IE 8/9 (I haven't verified for IE 10 but I've heard that the page renders incorrectly in it)

2) HTML Files with images->Open the relevant page in a default browser

Pros: Similar to above, except the page is more malleable in an HTML way

Cons: Similar to above, except now the images must be edited instead of the PPT file (a little bit more inconvenient)

3) Make a separate form

Pros: Feels native to the application. Displaying another form for help is often an expected behavior.

Cons: Realistically speaking, the developer is the only one who can update/modify the manual if necessary.

Or should I try to convince my manager and say that CHM files are the best way to go?

Answer 1

Anyone who has dragged their tired eyes through an Adobe or Apple support menu knows that the help menus developed by even some of the largest application developers fall short on offering contextual relevance. It is possible that this may be singularly the most valuable thing you could bring to an app, and it need not take a lot of coding.

Contextual relevance means that in addition to symantec driven search, or key word indexing of a help menu taxonomy, you have the most obvious help items right at hand. It requires knowing what the user is doing, which is not as complicated as it might seem.

You can make a big start, just by making the most obvious and straightforward, or most requested items immediately available at the top of a sub section of the help menu.

CONTEXTUALLY RELEVANT HELP MENUS

In this case, the user is working with a BRUSH, clicking HELP brings up Brush help:

Tool tips are a start, but in many instances you need a diagramatic or other graphical approach is required to show how a feature is used.

So the simplest approach is to have two sections to help - Contextual - starting with the page or tool bing used, and general, search based on common taxonomy or index.

There is a methodology to developing the information architecture, in terms of what are the most frequently asked questions, and establishing the right foundation to establish user confidence. (eg. you have to Open a document, before you can Edit, before you can Save etc.) This seems a matter for a chapter in a book rather than a simple post, but if anyone would like to continue with Menu Hierarchy we could drill down on that. It is largely based on intent, so its difficult to cover completely, but again, could be helped enormously by context. If someone is in the process of saving or sharing a document - you already know what they are likely having a problem with - start with that and give them the options. Sorting the options is going to involve a degree of trial and error.

I hope this is helpful or inspirational in some way, I try to keep things simple and my approach often seems like common sense.

Answer 2

I've been using the Zim Desktop Wiki for help systems for years. It does everything you've outlined. It's completely open-source and written in Python so it's easy to modify if needed (though I never have).

Everything in Zim is stored in plain .txt files using markdown formatting (similar to StackExchange) with a separate SqlLite database for each notebook's keyword index. Links can be made to other notebooks as well as any URL. There are also some ways to fire off programs and scripts by clicking a link. (I use it under Linux but there is a Windows version.) Images can be linked to or embedded.

File permissions can be used to limit modifications to the help files.

Zim's manual is itself a Zim notebook accessed with F1 or from the Help menu. I follow a convention of creating a "notes" sub-page under the relevant supplied help page for my annotations in order to preserve the original, but I could just as easily edit or add to the original and it would be instantly indexed and searchable.

If you want a help system your client can add to and customize without needing a programmer, Zim is worth looking at.

Answer 3

The preferred solution is to not need help systems. If you need help, focus on what the help is addressing first. Sometime you can resolve the confusion at the UI level.

Beyond that, there is no preferred option other than it's best that the help be relevant to the particular needs of the user. Contextual help obviously being better than not having contextual help.

How you create it isn't really a UX issue. That's a production question and is really going to depend on the staff that have to write and maintain help documentation.