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.
Heidi Colonna reports: <<Our shop is planning (in the near future) on
moving from .pdf guides, mostly user guides, to HTML user guides. In
doing some research online, it appears that HTML guides are not all
that different from online help systems as far as the chunking of
information/topics. The only major difference I've noticed is that in
help systems you have a TOC and in an HTML guide you have a list of
links.>>
It's a bit more complicated than that. At its core, the information is
identical, as is much of the interface--that is, both are a series of
pages (topics) reached by links and cross-references. So pretty much
anything you can do in one format, you can do in the other, with
varying degrees of ease. In what follows, I'll say "HTML" when I mean a
tool such as DreamWeaver; in contrast, Help and HTMLHelp mean the
Microsoft formats.
In terms of the technology, Help files are most often a compiled
format, usually restricted to a single operating system (or when
they're nominally cross-platform, they're typically suboptimal on other
operating systems), whereas HTML can be made fully cross-platform with
minimal effort--you just have to write to the standards and keep it
simple instead of using all the bells and whistles your users don't
need. You also won't get a search function built-in with HTML, and will
have to find one and add one, or figure out how to link the pages to
your operating system's search tools.
In terms of the content, the TOC difference isn't really a difference.
A compiled Help TOC may be automatically generated, and may
automatically support a collapsible/expandable tree of topics, but you
can do the same in HTML. (_I_ can't, but I've seen it done, so it's
just a matter of figuring out how.) A table of contents does not,
itself, change--only how you create it and display it. And imho, any
help system that doesn't have at least one table of contents
(preferably a few, with special purpose ones to meet special needs) is
useless.
What's missing in HTML are two main things: First, automatic linking to
program features such as dialog boxes is missing from HTML; this means
that if you want to create context-sensitive help (and why wouldn't you
in this day and age?) you have to manually create topic IDs or
comparable identifiers (unless a tool such as DevaHelp* does this for
you) and you have to teach your programmers how to link to these
topics. Not difficult, let alone rocket science, but not as convenient
as using something like WinHelp that is so firmly engrained in
programmer culture and programming tools that it's a no-brainer.
* See: http://devahelp.com/ (also includes indexing and search
functions). Windows-only, unfortunately, so I can't use it on my Mac
and thus, can't provide details. Strikes me as a silly choice given
that it works via Dreamweaver, which I do have on my Mac. Why not write
it in Java so it works on all platforms?
Second, no HTML tool encourages you to create an index as you go. I
personally consider a help system useless if it doesn't have a _good_
index, so... Indeed, if you don't research the topic, you won't know
that indexing HTML is even possible. DevaHelp includes built-in
indexing tools; you can also look up HTMLIndexer
(http://www.html-indexer.com/) if you prefer a strong standalone
product that focuses exclusively on indexing if you don't want to adopt
a full package such as Deva.
<<Some of our guides use information mapping (IM) procedures. In
playing with the HTML output of guides with these IM tables, the
information mapping tables are lengthy and look bad.>>
That's a problem with your use of the tool, not with the tool itself.
Information mapping is ***NOT*** about rigid tables, though a casual
glance might mislead you into thinking so. My main criticism of IM has
always been not with the philosophy--which is powerful--but rather with
the fact that users so often forget this philosophy and start thinking
only in terms of tables. If all you have is a hammer...
Instead, IM is, in part, about using the concept of a table (chunking
and categorizing and using white space to organize information) to help
you structure your data. If you've used the method appropriately, and
have focused on dividing up the information appropriately, it should
take a relatively minor effort to figure out how to redesign the
information to work in HTML.
<<My sense is that as we move to HTML, in our documentation that uses
the IM method is going to have to be changed.>>
Not really. The format will have to change, but not the process of
analysis used to generate the information that you will present using
that format. Moreover, it's ironic that you raise this point given that
Robert Horn (the inventor of the infomapping method) was also one of
the early "names" in hypertext design*. It seems to me that information
mapping should translate logically and very efficiently to online uses
if you focus on the philosophy rather than on the tables.
* See, for instance, "Mapping Hypertext: The Analysis, Organization,
and Display of Knowledge for the Next Generation of On-Line Text and
Graphics" (1990). I believe there's a much earlier book too, but didn't
go looking.
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
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.componentone.com/TECHWRL/DocToHelp2005
