Formats for User Documentation

[Evan]

I am exploring options for user documentation formats for solutions created using FileMaker Pro. Specifically, whether our documentation should be in a PDF file, a set of HTML pages, or presented using some kind of help viewer as is common on both Macintosh and Windows operating systems.

The idea of using a help viewer is particularly appealing for its consistency with the user experience of other applications on these platforms. However, glancing over developer documentation on how to use these help viewers it seems that you must call certain APIs within your application to implement them. Since we have a "FileMaker Solution" and not an actual application, therein lies a problem.

Any suggestions on user documentation formats, links to standards/guidelines, or how to use help viewers will be appreciated.

[Anatoli]

I do not fully understand what is the aim.

You can always construct HTML page with anything you need, and put script step Open URL into script. Then you can call that script from button Help...

[Fenton]

This is a good question. There are several options. As Anatoli says, there is always HTML. You would need to know the filepath to your main page, but this is easily available from within FileMaker, using calculations and the Status(CurrentFilePath) function; as long as the Help file are in a specific place in the solution's folder(s).

PDF is also a good alternative, with its chapters, and a built-in search engine (which is not readily available in HTML; if anyone knows one please chime in). PDF's can also be opened with the OpenURL step, as long as Adobe Reader (or Preview) is properly configured on the machine (which it usually is).

A basic question is "How interactive is this going to be with the database files?" The two formats above are best used when there is little interactivity. Actually, HTML could be interactive, if you used specific URL's for different pages within the database. It would be somewhat "hard-coded" however; but all methods are that way to some extent, as compared to a standard database file.

To have a high level of interactivity, ie. jump directly to Help pages from all different places in your files, the Help file can be built with FileMaker itself. There a two different overall methods to use. I wrote an article about this once: http://fentonjones.com/Articles/23_Help.html

There is also an example file, part of my FM_101 learning solution (29 articles, many with example files) which is available on my downloads page:

http://fentonjones.com/files/Downloads.html

The easiest is to use layouts, ie. enter your text and graphics in Layout mode. Then all you need is a bunch of Go To Layout scripts; or a cross-reference somewhere to match up layout numbers (which can be pointed to in scripts) with layout names (which can't). This method is best for Help files that have a fair amount of graphics (screenshots, etc.) mixed with text.

Another method is what I think of as "records-based." It's much more like your standard FileMaker file, with the help text in a text field, navigation by going to the record, "table of contents" being portals based on self-relationships.

This method is perhaps the most flexible, as far as adding new help records, rearranging them, etc.. It is not very flexible as far as mixing graphics and text, as they are both fields; but you can have a few different layouts to handle some variation.

A third alternative, using FileMaker, is to buy one of the available templates for help files. Most of these use the "operating system" style of clicking a triangle and having the subtopics drop down. They look pretty slick, are not that expensive (perhaps even free), and would be hell to build from scratch yourself (the above being difficult in FileMaker).

Here's a few:

HelpMaker (free) http://home.hiwaay.net/%7Ecullman/files/HELP2.zip

ClickHelp (free) http://www.clickware.com/products_clickhelp.htm

CCHelp http://www.clevelandconsulting.com/HTM_Flash/Products/CCHelp.htm

Pro Help http://www.onegasoft.com/

List of all: http://www.fmfiles.com/dev9.html

[kennedy]

A lot depends upon what level of documentation you intend to provide (or need to provide) given the complexity of your application. That affects how extensive the display needs to be (for example, is it sufficient to give one-liners or will your documentation be extensive with tables and graphics and tutorials and such). Also, the nature of the application and its target platform may affect the decision... if its designed to feel like a Mac app for a Mac community, I'd want the help in the normal Mac help system (so to speak).

Since you said you were "exploring options", let me point out another beyond Fenton's good list...

I like to give the user a consistent way to get quick help on individual fields and buttons... just hold "shift" when you click on any field title or button you see and it displays the help text for that field or button. Rather than use pop-ups which get in the way and must be closed, I display such help text in a single/common help/status area. That works great for "one-liner" help... not good at all for more extensive help needs.

For a concrete example of this, grab my Starter Template out of the Sample Files forum.

You can also mix and match help formats... use a FM-based technique for quick-help on individual elements, and an OS-native or HTML form for more extensive user manual and tutorial type documentation.

Hope that helps.

[Somnimedia]

I'm very impressed by ProHelp:

http://www.onegasoft.com/tools/prohelp/index.shtml