Boston Broadside
March/April 2002
Vol. 59,  No. 4
    Newsletter of the Boston Chapter of the Society for Technical Communication

Inside

Copyright © STC Boston 2002

Program Report

The Road Less Traveled:
Creating Web-Based Help with Dreamweaver

By Anne Louiselle

  John Garison, Taryn Light
  John Garison and Taryn Light, First Vice President of the STC Boston Chapter
  Photo by Anne Louiselle
When developing HTML-based help systems, using traditional Help Authoring Tools (HATs) seems logical. Why would you choose otherwise?

"You can use nontraditional tools to develop a help system. You won't be alone," said John Garison, Documentation Manager for Integrated Development Enterprise (IDe).

In fact, you may end up with a very effective product and an easy development process. At the December 12, 2001, meeting of the Boston Chapter of the Society for Technical Communication, more than 100 people heard Garison provide a case study where his use of nontraditional tools proved to be the better option for his project.

The Challenge

John Garison is the Documentation Manager for IDe. The company's product, IDweb, is Internet-based development chain management (DCM) software. IDweb helps CIOs, project managers, and other employees of large corporations manage hundreds of projects.

Although IDweb already had a help system, Garison decided it was time to enhance it. His challenge was to develop a new and more extensive, cross-platform, cross-browser help system in HTML.

Garison's team consisted of five technical writers. The new help system, IDweb Help, needed to be developed in five months. This was a mighty challenge indeed.

  John Garison
  John Garison explains how to create a Web-based help system with Dreamweaver
  Photo by Anne Louiselle

The Considerations

After looking at traditional help tools, Garison chose Dreamweaver from Macromedia, Inc. (http://www.macromedia.com/software/dreamweaver), a high-end Web site authoring tool. Although Dreamweaver is generally used to produce full-featured Web sites, it also can be used to create help systems.

To Garison, two factors were important. "It made sense to use Web tools for Web help. Almost anything you can do on the Web, you can now do in help," said Garison. "In addition, I wanted to be free of the limitations of traditional help authoring tools. Our previous tool had given us lots of trouble, losing graphics and dropping links. We wanted to be in control. We did not want conversion results," he added.

  P.J. Gardiner, John Garison
  P.J. Gardiner, Information Architect at CitiStreet, and John Garison
  Photo by Anne Louiselle

The Development Process

Garison provided an overview of the development process. "In order to move forward on the project, we developed a file structure. We created a page level directory for all page-level help topics. Each application page had a corresponding help page. We created a general directory for common topics and directories for module specific pages. Next, we developed templates and style sheets and set up source code controls. Once the basic file structure was in place, we divided the application sections among the writers and proceeded with the project."

During the process, Garison was able to expand his idea of focusing on a Web user audience. "Since our users are Web and browser users, we were able to abandon the traditional Table of Contents and Index, and use a search engine, relevant links, and a role-based contents page."

To develop the search feature, Garison's team used Deva ToolsTM for Dreamweaver, from Deva Associates (www.devahelp.com), which helped them to locate files with relevant information.

The Results

Garison is pleased with the help system of over 900 pages. "The results work. Our support people and the customers love the results, especially the search capability. It takes the load off the training personnel to teach click sequences," said Garison.

  Emma Mount, Susan Russell, Anne Ladd, Rick Walsh
  Emma Mount, TAC Worldwide; Susan Russell, TAC Worldwide; Anne Ladd, Contractor; and Rick Walsh, McKesson
  Photo by Anne Louiselle

Is this Tool Right for your Project?

When starting a new project, many technical communicators are faced with the difficult task of determining the best route. Many assume that the more traditional plan of using Help Authoring Tools to create a help system is their only choice.

Although every project requires special considerations and no one solution answers all problems, Garison provided some insight on how he was able to determine that Dreamweaver was the appropriate tool for his project.

First, he spoke to Dreamweaver users. Then he used the 30-day trial copy to test the product. Dreamweaver provides powerful diagnostics, such as a broken links report. This helped Garison and his team monitor the pages that they needed to develop. Library items helped them too. They saved text, links, and pictures as library items, which they could drag and drop on to a page.

Garison knew that he needed to choose a product that could be easily used by his team. "I found that Dreamweaver could be easily used by my team of writers working on a single code base," explained Garison.

Attendees found Garison's presentation interesting. "This was quite helpful for someone like me who doesn't use the tools," said one attendee.

"Very informative! I wasn't aware you could develop help without a traditional HAT," said another.

"I am a writer starting to work on Dreamweaver. It's helpful to see how a writing team used the product," commented one technical communicator.

"I'd like to see more practical applications and approach topics like this one," commented another.

Tips

For training, Garison recommends Ben Weisner's Dreamweaver seminar (http://www.weisner.com). Garison sent a writer to this seminar and highly praises Weisner's approach.

In addition, Garison suggests setting up a key toolsmith person. The toolsmith should create the templates and act as the key person to answer questions.

Garison's recommendations for resources include the user group for Help Authoring Tools and Techniques (http://groups.yahoo.com/group/HATT) and HelpWeavers (http://groups.yahoo.com/group/Helpweavers).

About the Speaker

Garison has been a software documentation writer, manager, consultant and teacher for over 25 years. He has spoken at conferences in the United States and New Zealand, and is a former principal of Help University. For more information, visit Mr. Garison's Web site at http://www.garisons.com.

Drawing Recipients

Ben Weisner and the folks at Deva (http://www.devahelp.com) donated a Deva Search license. Darlene Doehrmann of Healthcare Automation, Inc. was the lucky recipient of this drawing.

The Boston Chapter of the Society for Technical Communication held a second drawing as a membership drive incentive. As lucky recipients of the "Bring a Guest Drawing," STC member Carol MacBain received $25 and guest Anne Morganto received $25.

Anne Louiselle has been a member of the STC since 1997. Anne can be reached at .

Resources