Field-level context-sensitive help for web-based applications?

Subject: Field-level context-sensitive help for web-based applications?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: techwr-l -at- lists -dot- raycomm -dot- com, Karen Casemier <karen -dot- casemier -at- provia -dot- com>
Date: Tue, 03 Feb 2004 16:26:48 -0500

Karen Casemier wonders: <<Are any of you providing field-level help for a web-based application? If so, how are you doing it?>.

I'm not, but a few thoughts based on the work I've done in online help systems:

<<In our first prototype of a new web-based application, the developers used tool tip technology instead of true field help. This concerns me for a couple of reasons: Tool tips were not designed for things like 300-character field definitions. They were designed to provide a few-word description of icons.>>

Agreed, and this is precisely the kind of problem you want to elimate at the "first prototype" stage; if you don't squash it now, it'll become part of the future interface and the resistance to change will be far more difficult to overcome. Ask the programmers to play around with the tool tips from some other programmer's module (i.e., one where they're not intimately familiar with the code) and they'll understand why you see this as a problem.

A tool tip says "this is what this widget does", not "here's everything you need to know about the widget". I'll bet that Microsoft's guidelines for developers say much the same thing, and perhaps even specify a character limit. A more standard approach would be to build affordances into the interface. For example, rather than adding a several-hundred-character tip that defines the date format, why not change the field name from "Date:" to "Date (yyyy-mm-dd)" or even three subfields labeled "year", "month", and "day"? And so on.

<<We cannot include links within the tool tips for more information. I think a context-sensitive field description should be informative but concise. The only way to truly do this is to provide links to additional information about concepts discussed in the definition.>>

If you can't build context-sensitivity at the field level directly into the interface (this probably depends on what development tools are being used), you can at least provide context sensitivity at the level of the screen or dialog box. That's a standard approach in software and help development, and should be an easy sell. You can either do this directly in the development tool (if it supports such help), or simply provide a "Help!!!" button at the top of each screen that links directly to an HTML file for that screen. I know this is easy to do because it's how my former colleagues developed help for some Delphi databases.

<<-With the tool tips, we have to provide an .xls file with token names and field descriptions, which is then copied into the database. I'd prefer to retain control of the field-level help and keep it as part of the main help system, and remove the burden of updating and maintenance from the developers.>>

If you're the one who generates the .xls file, all you need to do is notify the developers that you've updated the file (corrected errors, added new labels, whatever) and that they must now reintegrate it in the database. You mentioned that you "want to make their jobs easier", which means you can probably work with them to develop a way of meeting this goal. Perhaps they'll even give you direct access to the database once they learn you won't muck it up.

<<currently, the only way we can envision a more appropriate type of help is through custom coding for each field.>>

That sounds fishy to me. It should be trivially easy to assign a context ID to each field in a dialog box or to each dialog box, then add a simple line to the code for the event handler: "If F1 is pressed with the cursor in this dialog box, call the procedure that displays a help file for the context ID # specified for the appropriate field". I (a very amateur programmer) did this something like 20 years ago in Pascal, so presumably it's much easier with modern software.

Of course, it will take a measure of tact suggesting that your programmers are too lazy to have considered this option <g> or don't read the manuals for their programming SDK <g>. Proof left to student. <g>

--Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)

Field-level context-sensitive help for web-based applications: From: Karen Casemier

Previous by Author: Comparison of tech writers and science editors?
Next by Author: "Breadcrumbs" in Dreamweaver?
Previous by Thread: Field-level context-sensitive help for web-based applications
Next by Thread: Re: Field-level context-sensitive help for web-based applications

What this post helpful? Share it with friends and colleagues:

Sponsored Ads