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.
I fully agree with Geoff on the use of IM. I was an IM instructor in a
former life, and I have done (and still do) many IM documentation
projects in different software tools. It's not about tables (for
example, I'm using numbered lists for steps, not step/action tables).
It's about -among other things- chunking, infotypes, and consistency.
BRs
Wouter
>-----Original Message-----
>From:
>techwr-l-bounces+wouter -dot- verkerken=swift -dot- com -at- lists -dot- techwr-l -dot- com
>[mailto:techwr-l-bounces+wouter -dot- verkerken=swift -dot- com -at- lists -dot- techw
r-l.com] On Behalf Of Geoff Hart
>Sent: Saturday, April 08, 2006 5:11 PM
>To: TECHWR-L; Heidi Colonna
>Subject: HTML Guides?
>
>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.
>
>- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
>Geoff Hart ghart -at- videotron -dot- ca
>(try geoffhart -at- mac -dot- com if you don't get a reply)
>www.geoff-hart.com
>- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
>
>^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
>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
>
>---
>You are currently subscribed to TECHWR-L as Wouter -dot- VERKERKEN -at- swift -dot- com -dot-
>
>To unsubscribe send a blank email to
>techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
>or visit
>http://lists.techwr-l.com/mailman/options/techwr-l/wouter.verke
rken%40swift.com
>
>To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
>
>Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
>http://www.techwr-l.com/techwhirl/ for more resources and info.
>
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
