Moving to HTML-Based Help: A Strategy Workshop November '99 Meeting

Meeting Leader: Cheryl Lockett Zubak Written by: Zyppora Goldberg Originally published in News & Views January 2000 issue. Copyright 2000 STC-Philadelphia Metro Chapter. For permission to reprint this article, contact the Managing Editor.

In November, online help expert Cheryl Lockett Zubak led forty-four participants in an all-day workshop on strategies for developing hypertext markup language (HTML)-based help systems. The workshop was held at SCT Corporation in Malvern, PA. HTML-based help is becoming more prevalent as WinHelp wanes. Microsoft continues to support WinHelp but is not updating it. HTML-based help is created with HTML rather than the rich text format (RTF) used in WinHelp. HTML-based help is developed using either standard HTML or custom software with an HTML foundation. It may be compiled or uncompiled depending on the development environment, and it can be supported and enhanced by software controls such as Microsoft's ActiveX controls or Java applets. The workshop covered the advantages and issues in using HTML-based help, design and development environment models, authoring tools, WinHelp conversions, and future trends. Advantages of HTML-based help Cheryl cites the following advantages to creating HTML-based help: Extensive HTML learning support Because HTML is widely used, you have many educational resources: paper-based and web magazines web development sites with tool reviews, tips and tutorials; for example, webdeveloper.com and webreview.com conferences and training opportunities; for example, WinHelp, Help University, TechComm, and WinWriters Solution Extensive authoring tool support You can use new versions of traditional help authoring tools or one of the many HTML editors on the market. Utilities are available to help you create graphics, set up and manage sites, check links, and track errors. Enhanced help features sophisticated pages push delivery of unrequested information and pull delivery of requested information flexible display of the table of contents and index full-text search information type tagging (can be used to hide or show information based on the type) built-in linking to the web using standard HTML links dynamic updates from the web (problematic for a compiled format) embedded help (much easier in HTML-based help than in WinHelp) Better graphics support The graphics standard for HTML-based information is much higher than for WinHelp. Web graphics don't have the same palette, scaling, and skewing problems although new problems do exist. You can use other graphical formats with or without software support. Improved HTML formatting Tables, frames, and style sheets available in newer versions of HTML have made it easier to format HTML information. You can even add borders or shading to tables. Extensible markup language (XML) and dynamic HTML (DHTML) continue to improve HTML formatting. You can use XML to describe HTML pages by structure and reformat information. You can employ the HTML style sheets and scripting in DHTML to make HTML more software-like. Extensible file format You can add scripting to HTML to do more than you can with WinHelp macros. You can use Common Gateway Interface (CGI), Perl, and JavaScript on the server, and you can take scripts off the web and revise them. You also can extend HTML with software controls, such as Java applets. Support for interactive information scripting (forms, application simulation, conditional tests) DHTML animation, video, sound new web applications (for example, Macromedia Shockwave for developing vector-based animation) Note: Additional software support may be required for some interactive functions. Feasible updating of information You can upload updated help files to the server and have users retrieve the information. At this time, you cannot update compiled files incrementally. Information layering over physical locations A single help system can contain pages that are stored locally, on an intranet, and on the web. You can specify local and remote alternatives for a single link. Issues in using HTML-based help Cheryl encourages us to move to HTML-based help keeping the following issues in mind: Browser deployment HTML-based help may require users to have a specific browser installed on their computers. Cross-platform support HTML-based help does not work across all platforms yet. The Java programming language is being used to develop cross-platform help; however, users must have the Java Runtime Environment (JRE) or virtual machine (VM) installed on their computers to access the help. Cross-browser support Some HTML extensions are not compatible with both Netscape Navigator and Microsoft Internet Explorer (IE). To provide help across browsers, you may need to code two versions of help, or you may be restricted to using standard HTML features. You also may want to investigate using Sun JavaHelp as an alternative lightweight browser. Features different from WinHelp HTML-based help does not include temporary popups that support complex formatting or macros with standard parameters. You can use scripting to replace these features but it may be more difficult. HTML-based help also leaves a much larger footprint than WinHelp. Audience Our audience has not changed. We shouldn't assume that all users have web connections and are experienced web surfers. Basic design models There are four design models for HTML-based help: tripane, scripted, website, and embedded. Table 1 summarizes the features of each model. Choose the model that fits your organization's product requirements. In designing your help system, you need to decide if you want to take an HTML-centric or software-centric approach. HTML-centric approach With an HTML-centric approach, you create help in standard HTML and have users download all information from the server. Users have a browser installed on their PCs, but they do not need to store any help software. This type of installation is referred to as zero client or thin client. You can use some software controls in an HTML-centric help system including: plug-ins for certain types of content support navigational systems server-based or client-side search facilities When you use an HTML-centric approach, you have a high degree of control over content design, especially if you use style sheets. On the downside, HTML-centric systems are often slower than software-controlled systems. Software-centric approach With a software-centric approach, you support HTML with additional software components for certain design aspects, typically, navigation. Users have to download these software components on their PCs from the server or a CD-ROM. By incorporating software controls, you can enhance your HTML content base and create a more usable user interface by providing: navigational and other controls (button bar versus embedded content, associative links, information types) expandable/collapsible table of contents and index search interface better user feedback (tracking topics in the table of contents) increasingly robust help (as the software technology becomes more robust) Some disadvantages of using a software-centric approach are limited cross-platform compatibility and dependence on third-party software vendors. HTML-based development environments You can develop HTML-based help using standard HTML, Microsoft's HTML Help, and Java-based help. Table 2 summarizes the features of each environment. Authoring tools To create HTML help, you may use a variety of tools: a help tool, an HTML editor, a structural tool, a validation tool, animation and multimedia tools, and scripting and DHTML tools. Your choice of tools depends on: what you are creating and from what you are creating it how much control you want your authoring bent; that is, visual versus coding your deployment requirements When you shop for a tool, create a realistic prototype, then review marketing sheets, check out the vendor's technical support, and get some basic training on the tool if possible. Understand that you may need to compromise or use multiple tools to get what you want. Help tools There are four help tool models: Print-to-hypertext Create HTML-based help from a printed document or hardcopy format. You use fairly sophisticated markup to export the document to an online format. Print-to-hypertext tools include Doc-To-Help (WexTech) and HDK in conversion mode (Virtual Media Technology). Tag tools Create each help topic in a constructed approach using the tool interface to tag the content with HTML codes. RoboHELP Classic (Blue Sky Software) is a tag tool. What you see is what you get (WYSIWYG) tools Create help in a visual format to emulate the actual viewing environment. ForeHelp (ForeFront) and RoboHELP HTML (Blue Sky Software) are WYSIWYG tools. Database environment tools Create help from information in a database. This type of tool enables you to make efficient reuse of information. Database environment tools include ForeHelp, HDK, eAuthor Help (Delphi), and RoboHELP Explorer, an HTML project manager. Help tools offer many benefits: mature structuring capability for project management, indexing, table of contents creation, and browsing support for context-sensitivity, compiling, and special linking functions conversion capabilities for Word import/export and the ability to create multiple types of HTML-based information These tools do have some problems: don't always create clean HTML code may change scripting or style sheets you have created outside the tool limited HTML-handling choices not everything is supported; for example, secondary windows particular problems with windowing, merging, and extensions HTML editors HTML editors do not support HTML-based help, but you may want to use one in combination with a help tool. An HTML editor is better for generating HTML (usually) and web documents and for working with frames, style sheets, DHTML, and scripts. HTML editors include ColdFusion (Allaire), Dreamweaver (Macromedia), Drumbeat (Macromedia), FrontPage (Microsoft), HomeSite (Allaire), HoTMetaL PRO (SoftQuad), and Visual InterDev (Microsoft). Cheryl's top picks are HomeSite and Dreamweaver. Converting from WinHelp to HTML-based help Here are some basic steps for converting your documents to HTML-based help: Decide if you want to convert your help or start over. Map your existing documentation. Develop a prototype. Determine a conversion strategy. Will it be easier to reorganize information before or after the conversion? Do you need non-convertible items? Consider that certain items will be handled differently in HTML or may not be present; for example, bullets and numbered lists, titles, popups. You may need to recreate the user interface. Do a test conversion. Do more markup or fixes in Word or the environment with which you are familiar rather than in HTML. Repeat steps 5 and 6 until you are satisfied with the process. Convert your help. You may be able to use the same help tool that you used to create WinHelp. Many of these tools have new features for handling HTML-based help: interface improvements, additional conversion capabilities, database tools with added support for HTML and HTML-based help, HTML-based help "native" tools, and extensions for enhancing HTML-based help. Future trends Cheryl sees the following trends in HTML-based help: DHTML user interfaces more embedded help zero client installations Cheryl believes that HTML-based help is "one of the most important things to happen to technical writers in a decade." It enables help authors to "create more interesting, more accessible, and eventually more easily distributable content." It will bring help authors greater visibility and acceptance in their organizations because HTML is used by other professions and companies recognize its importance. Knowledge of HTML will increase technical writers' marketability and may provide an opportunity to move into other departments. What skill sets should help authors have for the year 2000? Get experience in content development, help and online book design, and HTML technologies . Table 1. HTML-Based Help Design Models   Tripane Scripted Website Embedded Description Uses vendor-specific HTML interface (Microsoft, Sun, Oracle) Uses standard HTML for content Uses scripting to control window size and navigation Looks like small frame-based website All content is stored on server Uses standard HTML for content and may use scripting All content is stored on server Can be used on web or standalone on intranet or CD-ROM Help is built into the software Topic Design Single topic Multi-topic Multi-topic Multi-topic Page Design Three Panes: First pane Navigational button bar Back, Forward, Home, etc. Second pane Contents: expandable/ collapsible Index: keyword search Find: full-text search Third pane Content area Scrollable Five Frames: Frame one Controls for contents, index, find Frame two Graphical navigational controls Uses graphics to represent the main documents Frame three Contents or keyword list Frame four Content Frame five Browsing Printing Exiting Includes frames and tables. Top frame contains navigation to different content areas/chapters Browsing embedded in the content for top frame Typically graphical and created by hand May use scripting to control browser sequences Pages often include more specific tables of contents Links in table of contents may be embedded in contents Two basic types: Dialog-level (typically text in dialogs) Persistent window for topic content Browsers Microsoft: IE 3.02 or higher (4.0 recommended); IE doesn't have to be open or be default browser Sun and Oracle: Java-enabled browser Navigator 3.0 (NetHelp 1.0) or Navigator 4.0 (NetHelp 2.0) or higher Works across browsers although some extensions may not be compatible with all browsers - Comments Navigational aids always present or accessible in other panes Larger claim to real estate than standard WinHelp designs Not cross-browser No full-text search; Find from Navigator Full-text search is common but not guaranteed Keyword indexes are unsophisticated Requires help authors to work closely with interface designers and developers Examples Blue Sky RoboHELP HTML, Microsoft IE Help, Sun JavaHelp, Oracle Help Netscape NetHelp Macromedia Dreamweaver Microsoft Money Table 2. HTML-Based Development Environments Standard HTML (World Wide Web Consortium [W3C]) HTML Help (Microsoft) Java-Based Help Sun JavaHelp Oracle Help Description Governed by the W3C Microsoft's new help development environment Uses custom software and HTML foundation Supports standard HTML and DHTML Sun Microsystems product Uses Java and HTML foundation Supports most features of HTML 3.2 and some of the same extensibility features Supports Oracle applications Supports a client/server environment Adopts JavaHelp as application program interface (API) with Oracle interface Format Uncompiled Compiled or uncompiled Compiled Compiled Windows and Topics Single window standard but changing Multiple topics per window Tripane window Multiple windows Single topic per window Popups Embedded help Single window handling built in Single topic per window Popups and secondary windows (requires coding) Single window handling built in Single topic per window Navigation Part of the content rather than the browser Linking to local or remote content Table of contents in frames or tables Combined index/full-text search Table of contents Index Full-text search Favorites Table of contents Index Full-text search Dockable (detachable) navigational pane Expandable/collapsible table of contents Keyword and full-text search Requirements Zero client installation Works with different browsers With ActiveX control (all features) IE 3.0 or higher (4.0 or higher recommended) Runtime files (HHUPD.EXE) 32-bit Windows With Java applet (limits features) Any Java-enabled browser Java components Cross-platform Any Java-enabled browser (SWING content viewer is default) Any platform with Java Virtual Machine (JVM) Java Runtime Environment (JRE) installed on user's machine (about 18 MB if Java Development Kit (JDK) is not installed) A Java-enabled browser (HotJava or ICE is default) Any platform with JVM JDK 1.1 or higher Advantages Common format is foundation of all HTML-based help Handles many graphics formats designs Very extensible Rich multimedia capabilities Scripting (JavaScript, Jscript, VBScript) DHTML Support additional software components (for example, ActiveX and Java applets) Cross-platform potential Can get assistance from large community of developers Microsoft sets standard we must consider Built-in software control of features that require a good interface Context-sensitivity Compressed format Rich link handling Same extensibility as standard HTML Help extenders available from tool vendors Application program interface (API) comes with recommended user model and can be customized with programmer help Context sensitivity (built into JDK 1.2 API) Built-in software control of features that require a good interface Cross-platform potential Great potential for intranet development Software extensibility Built-in software control of features that require a good interface Detachable navigational pane Cross-platform potential Conversion support for WinHelp 4, HTML Help, and JavaHelp Can use your own authoring tool to create the files Context sensitivity Disadvantages Changing Requires handling many , often complex technologies Can be slow Different HTML versions Different browsers have different capabilities Formatting more fixed than RTF but stylesheets are improving formatting No built-in context-sensitivity No popups but scripting and DHTML can be used to create them Popups don't work the way they do in WinHelp No secondary windows Quirkiness; doesn't always perform as promised Not cross-platform Difficult to customize software component Uncertainty about Java JVM difficulties (client requirement) Non-commercial default browser No support for latest version of HTML No support for stylesheets or DHTML Large software component on users' PCs Success with Windows questionable Potential need for programmer intervention Focus on Oracle's authoring needs Non-commercial default browser Conversion model is self-limiting No direct authoring tool support Success with Windows requires Microsoft support No popups

Return to . . .

[News & Views] [STC-PMC Home] [STC Home Page]
Last updated: February 9, 2000 (mvh)