TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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)