Columns

Online Help Outputs

By Nicky Bleiel | Senior Member

This column is a quick reference guide exploring “essential” technical communication topics. Please send questions or comments to Nicky Bleiel at nickyb@componentone.com. Follow her on Twitter @nickybleiel.

This quick reference outlines the most common online Help outputs for software documentation. Online Help in a software application is customarily a complete reference that has a table of contents, and is searchable and indexed. (Help for mobile applications is the exception.) Online Help should also be context-sensitive (dialog boxes/screens include help buttons or icons that open the appropriate Help topic) within the software application if possible.

Help Output

Details

Final Deliverable File(s)

HTML Help OS: Microsoft Windows

Released by Microsoft in 1997; compiled HTML files. Only one file (.chm) needs to be included in software install. The tri-pane interface (navigation buttons on top, Table of Contents/Index/Search on the left, content on the right) provides several ways for end users to find information while topics display in the same window. HTML Help was the first Help output to offer the tri-pane interface, which is replicated in many other Help outputs. Locally installed HTML Help files (those installed on the end user’s client machine), work without issues. If you plan to install on a server, there are security issues: see http://support.microsoft.com/kb/902225.

.chm (All individual .html files, plus the TOC and index are compiled into one .chm, pronounced “chum.”)

Browser-based Help (Name varies by Help Authoring Tool or HAT) OS: Platform-independent

Uncompiled HTML files; the Help opens in the user’s Web browser. Can be posted on the Web, on a server, installed locally, or all three. Use “Mark of the Web” to prevent ActiveX warning in local installs: http://msdn.microsoft.com/en-us/library/ms537628(VS.85).aspx.

Multiple .html files, plus graphics, themes/skins, and other files (depends on project and HAT). All files should reside in a single folder to make distribution/installation easier.

WinHelp OS: Microsoft Windows

Compiled RTF files; first released by Microsoft in 1990. (Was replaced by HTML Help, but is still being distributed with many software products.) The table of contents and topics open in separate windows. Look and navigation not as user-friendly as newer formats. The WinHelp viewer is not included with Windows 7 and Vista, but it can be downloaded: see http://support.microsoft.com/kb/917607.

.hlp and .cnt (The .hlp contains all the topics; the .cnt contains the table of contents).

Help 2.0 OS: Microsoft Windows

Released in 2001, the Microsoft Help output used in Microsoft Visual Studio 2002–2008. Tri-pane viewer is called the Microsoft Document Explorer. Distribute this output only if your Help needs to be integrated with the Help for Visual Studio 2002–2008.

For more information, see http://msdn.microsoft.com/en-us/library/bb165722(VS.80).aspx.

Microsoft Help Viewer 1.x (now 1.1) OS: Microsoft Windows

Released in 2010, the Microsoft Help output used in Visual Studio 2010. Visual Studio 2010 includes the Help Library Manager. With it, users can choose to view the Help “online” (on the web, opens in a browser) or “local” (the Help is installed on their machine, and opens in the Microsoft Help Viewer, a tri-pane interface). Distribute this output only if your Help needs to be integrated with the Help for Visual Studio 2010.

Multiple XHTML files, all zipped into .mhsc (Microsoft Help Containers). For more information, see http://msdn.microsoft.com/en-us/library/dd776252(VS.100).aspx.

JavaHelp and Oracle Help OS: Runs in any environment where a Java Client or Java Enterprise is available.

JavaHelp is a Help solution for Java applications. It is HTML-based with a tri-pane interface. Released by Sun Microsystems in the late 1990s and in release 2.0. See http://download.java.net/javadesktop/
javahelp/jhug.pdf
and http://javahelp.java.net/.
Sun Microsystems was purchased by Oracle in 2009. Oracle Help is HTML-based help for Java and web applications. The newest versions of “Oracle Help for Java” and “Oracle Help for the Web” were released June 2011. Requirements and other details: www.oracle.com/technetwork/developer-tools/help/index-083946.html.

Multiple files (Helpset: .hs, map file: .jhm, toc and index files: .xml, topics: .htm); all zipped into .jar files (Java Archives).

Eclipse Help OS: All browsers, but the Eclipse SDK must be installed on the same server as the help system.

Released in the early 2000s, Eclipse Help was developed for Eclipse, an open source development environment from IBM. Eclipse Help has a tri-pane interface and can contain many plug-ins. See www.ibm.com/developerworks/
opensource/library/os-echelp/
.

Multiple files (.html files that can be stored in a zip file, plugin.xml, toc.xml) See http://help.eclipse.org/indigo/index.jsp (search on “User Assistance Support”).

Mobile Help OS: Varies by device

Standalone Help for mobile device applications is designed and optimized for the interface and browsers used on smartphones and tablets. Best practices include minimalist content and a shallow table of contents.

Depends on development method. It can be browser-based Help (HATs offer this option); if authored in the native language of the device, it will be delivered as part of the mobile app’s code base.

Nicky Bleiel (nickyb@componentone.com) is the lead information developer for Doc-To-Help (www.doctohelp.com). She has 17 years of experience in the software industry developing online Help, manuals, quick reference guides, training, videos, and more. Nicky serves on the STC Board of Directors.