Return to Home Page

Book Review:
Creating Effective JavaHelp

by Kevin Lewis. O’Reilly, 2000.

Reviewed by NANCY ALLISON
Boston Chapter

If you want to learn the nuts and bolts of JavaHelp, this book will help. Creating Effective JavaHelp, by Kevin Lewis, provides hands-on exercises that enable you to create a simple JavaHelp help system. Longer examples, with explanations and exercises,  show you how the basic elements of JavaHelp work together and how advanced features add value. You can work your way through the book using software no more sophisticated than Notepad. However, you must have web access to download JavaHelp 1.1, sample files, and errata information. See below for Web site addresses.

Successful Hands-On Instruction

 The book’s strengths are its hands-on sections.
  • Chapter 2 walks you through the creation of Helpset.hs, Map.jhm,  Index.xml, and TOC.xml – the four building blocks of any JavaHelp help system. Using .htm topic files you download from the book’s web page, you create and view a simple helpset.

  • Chapter 5 explores the same territory, this time in depth, using files from a larger and more complex helpset.

  • Chapter 6 shows how to use advanced controls to refine a helpset. You learn to create text and graphic buttons, and modify such elements as the navigation tabs, tool tip text, and word search index.

  • Chapter 7 expands beyond standalone help systems to show how JavaHelp systems are linked to applications. Application-, screen-, and field-level help are explained, as well as embedded help. Using sample application source code provided by the author, you connect your help in a hands-on exercise. This chapter assumes that the reader is familiar with Java programming. Since this reader is not, I followed the chapter to the best of my ability. The extensive examples seemed clear and direct. If I were working with an application developer who was unfamiliar with JavaHelp, I would open this book to Chapter 7 and hand it over.

  • Chapter 8 covers deployment of JavaHelp files.

  • The appendixes provide helpset tags, lightweight component tags for the JavaHelp API, and source code for the sample application provided by the author.

Broad Overviews of Design and Planning

 Chapters 3 and 4 provide a cursory overview of  help system planning  and topic design. The sections are too short to provide a real education in these subjects. Chapter 9 quickly reviews those help authoring tools that can provide JavaHelp output. Again, the treatment has a hurried feel.

Bookmaking

 The entire manuscript could have benefited from a thorough edit to remove wordiness and to correct logical flaws in organization. For example, the section titled “How Third-Party Tools Work” starts abruptly with several paragraphs on how to buy a JavaHelp authoring tool: make sure it has the features you need; make sure the price is right; get information from vendors; and review free trial versions. Not only is this information a nonsequitur; it is also unnecessary for anyone with the technical sophistication to read this book in the first place. The book contains more such passages than it should.

The Index is adequate but could stand improvement. For example, the discussion of ForeHelp mentions ForeHelp’s Related Topics Wizard. Realizing that I had not read any discussion of A-links in JavaHelp, I looked up “related topics” in the Index. Two of the three citations refer to “related topics” in a generalized sense. The differing meanings of “related topics” should have distinguished clearly and listed separately. Ultimately, I could not find a discussion of A-links in JavaHelp, so I still do not know if JavaHelp can use the output of the ForeHelp Related Topics Wizard. 

Don’t Miss the Downloads

 Getting started with this book would be easier if all downloadable files were listed under one heading. The downloads are not difficult once you find them, but I did some page-flipping and double-checking before I was sure that I had found everything necessary. Be sure to download the unconfirmed errors reported by readers; one reader in particular corrects a URL and notes problems and solutions for Solaris users.

Despite its flaws, Creating Effective JavaHelp delivers.

Relevant Web Sites

For the JavaHelp 1.1 and JavaHelp 1.1.1 upgrade:
http://java.sun.com/products/javahelp/

For the Creating Effective JavaHelp web page:
http://www.oreilly.com/catalog/creatingjavahelp/
Nancy Allison is a freelance technical writer specializing in online help. You can reach her at gardener@world.std.com.

Copyright © 2001 Nancy Allison submitted to the STC for use in Hyperviews:Online.

Section 508 — 2001 Conference Report — Practical Magic — Reluctant Trainer — Book Review
Resources & References — Home

Spring 2001 (Volume 4, #2)

Copyright © 1998, 2002 Society for Technical Communication