Documenting Applets

Subject: Documenting Applets
From: Tim Altom <taltom -at- IQUEST -dot- NET>
Date: Tue, 20 May 1997 07:40:30 -0500

I was perusing the Sun Java site recently to check out and download the
latest JDK. They have some nice demos up there, some with business
applications and real-time controls. Then it hit me...there wasn't any doc
for any of the applets. Nothing for the user.

It got me to thinking that intranets are encouraging companies to write lots
of little pieces of software to replace lots of big clunky apps. But big
clunky apps can usually justify having help files written for them. Applets
can't. Yet applets change rapidly, proliferate widely, and may have obscure
controls that made sense to the programmer, but were never tested with
users. The budgetary constraints of any software project are magnified
logarithmically for Java applets. Yet because applets appear and disappear
and morph quickly, users can't usually hit up their cubicle-mates for help.
The cubicle-mates probably haven't seen the thing either.

Now Java and its accompanying paradigm are poised to create a whole new
world of business applications that will bombard users. Has anyone out there
thought this through and figured out a way to give the users some online
help when they need it? Has anybody addressed it? Would HTML be an ideal
vehicle for help? Should an applet carry a control to create a new page with
a help frame? Should the help file be totally cross-platform? If it was done
in PDF, the Acrobat Reader would have to load, possibly further confusing
the user. But different browsers may handle the HTML version differently and
confuse the user again. Or perhaps help should be incorporated right into
the Java applet like a standard Windows help menu item.

I haven't actually bumped into the problem yet, but I imagine I will. Has
anybody seen it happen yet?

Tim Altom
Vice President, Simply Written, Inc.
317.899.5882 (voice) 317.899.5987 (fax)
FrameMaker support ForeHelp support
FrameMaker-to-HTML Conversions
HTML Help Consulting and Production

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
Search the archives at or search and
browse the archives at

Previous by Author: Fee Disclosure
Next by Author: Re: Shuttle documentation
Previous by Thread: Software Manual Basics
Next by Thread: Learning and Contributing

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

Sponsored Ads