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.
Subject:Two cool tricks for Web-based Help From:Geoff Hart <ghart -at- videotron -dot- ca> To:TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Fri, 17 Nov 2006 08:46:28 -0500
Thought I'd pass along a couple cool tips related to file management
and Help topics in the context of Web pages. The first one, first
described (in my experience) by Colin Dawson (www.info-
action.com.au), is so simple it's positively brilliant. Here's the
example Colin gave:
If your Web pages are ASP files, you'll be generating a series of Web
pages with names like "file.asp". Rather than obsessing over map IDs
and how to pass those along to the developers so as to make the help
context-sensitive, you develop a standard naming convention: use the
identical file name, but replace the .asp with .htm for the help
file's name. Away goes any need for a map file and numerical map IDs!
This approach is easy to extend: if the files produced by the
developers end in .htm, you add a small tag to the help file name:
thus, for page.htm, the Help file becomes page-h.htm or page-help.htm
if you don't feel the need to be concise.
Obviously, what this lets you do is work a bit more independently of
the Web developers (i.e., no need to exchange and verify map IDs)
because the naming convention is simple, consistent, and easy enough
for even a developer to use. <g> Of course, you still have to do some
QA, but much less than with map files because it's harder to
undetectably screw up an alphanumeric name than it is to mistype a
simple number, and easier to catch the error. I imagine the same
approach could be extended to conventional (non-Web) software too,
with a bit of fudgery to make the plumbing work: so long as each
screen, window, or dialog has a name, you can add -h to the name of
the help topic.
This first tip comes from a summary of an presentation by Colin at
the last STC annual conference, in which he discussed the use of
Flash files (loaded from pages named as described above) to present
the online help. That's the second trick. Not enough details in the
summary for me to say much more, but basically this approach takes
advantage of the fact that Flash is more standardized than HTML plus
javascript, and thus behaves more predictably across browsers and
platforms, because one company (formerly Macromedia, now Adobe)
controls development of the reader. But there are other cool things
you can do with Flash that are trickier to do in HTML plus its add-ons.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
