The Novell corporate publishing services group develops tools for the company's various documentation groups. Recently, the group was asked to provide a hypertext authoring tool for use in creating on-line help systems for Novell's products.

Consistent Structure for On-line Help
"One of our major goals was to enforce structure while authoring on-line help," says Tracy Smith, software engineer for the corporate publishing services group. Writers have to rely on training, experience, and trial and error in order to adhere to a structure or corporate standard, and sometimes that doesn't work. For example, one author might create an umbrella topic that combines conceptual and procedural information while another author might separate conceptual and procedural information into individual topics. Or, if the standard is for all Tips and Hints to be at the bottom of a topic, there is no way to enforce that. Authors who are unaware of the standard can place Tips and Hints throughout the topic without realizing they've broken the corporate standard.

To ensure a standard structure, Novell decided to base its hypertext authoring tool on Standard Generalized Markup Language (SGML). "We believe that SGML is the best standard for making the information last," says Smith. Novell also wanted its authoring tool to speed production by providing an easy way to manage projects, topics, links, graphics, context IDs, and index terms. This management automates many tasks and minimizes editing and compiling passes and rework.

Ease-of-Use With the Power of SGML
The corporate publishing services group selected Adobe FrameMaker+SGML software after evaluating several SGML-specific and non-SGML tools. "FrameMaker+SGML provides all the formatting capabilities of FrameMaker software - which many of our authors are accustomed to - and one of the best structured authoring interfaces," says Smith.

"Some of the software we looked at offered ease of use, but only for specific outputs, such as HTML or Windows Help. Others offered powerful SGML functionality but were difficult to learn and use. Only FrameMaker+SGML provided both: the power of SGML and the ease of use our authors expected.

"In particular, the FrameMaker+SGML Structure View is great. Authors can continuously view the document's structure in an intuitive outline format. And they can continue to take advantage of FrameMaker software's formatting capabilities. This is a major advantage over other SGML-based tools, which restrict the formatting options available when an author is using structure."

Integration with an Oracle database provides the project, topic, link, graphic, context ID, and index management. To speed the process of creating on-line help and to facilitate group authoring, Novell used the Adobe Frame® Developer's Kit to link the program to a database. The resulting tool is called HelpWise.

The Oracle database included in HelpWise contains thousands of topics in an on-line help project, as well as the links, index terms, and other information. Writers use FrameMaker+SGML to create the content. To add an index term, they simply select "Index Term" from the FrameMaker+SGML insert menu, and then choose the appropriate term. To add a See Also link, they simply select See Also from the FrameMaker+SGML Insert menu and then choose the appropriate topic.

Storing help topics and other objects in the database has two key advantages. First, when linking, writers can simply select topic titles from a dialog box. "This link management capability saves time and eliminates the potential for incorrect and 'broken' links when a topic title is changed or a topic is eliminated," says Smith. The second advantage of storing topics and index terms in a database is that multiple authors collaborating on a project have access to the same index terms and topics in the project, regardless of whether a particular topic is open.

HelpWise Also Greatly Simplifies Indexing
"When authors modify an index entry, HelpWise enables them to change the index term just once instead of finding every occurrence," says Smith. "And by keeping all the index terms in the database, we can leverage the work of creating an index for other projects, as well."

Multiple Outputs from a Single Source
When the writer has completed the project, HelpWise extracts the SGML from FrameMaker+SGML, extracts the metadata from the database, combines the two into a single SGML file, and then converts the file to rich text format (RTF). The RTF file is then compiled to create the final help file for the Microsoft Windows 95 platform. When Novell extends HelpWise, it will create Apple Guide files for the Macintosh platform, and HTML for Internet-based products.

A Model for Future Help Projects
Novell recently completed its first project with HelpWise. "The author reported that HelpWise saved him 20 to 30 percent in authoring time, even with the added complexity of SGML," says Smith. "The writer attributes the time savings to the features we added using the Adobe Frame Developer's Kit." The company is now using HelpWise to develop a 1,000-topic help file relating to localization, for use by Novell employees.

"We demonstrated HelpWise at the SGML '96 show and got tremendous response," says Smith. "We'll be promoting it internally and continually refining it to meet our needs. HelpWise was designed to allow for our users' changing documentation needs."

Solving Today's Needs and Accommodating Emerging Formats
"A typical SGML editing system cannot capably handle the type of hypertext documents we develop," says Smith. "With FrameMaker+SGML at the core, we have created an SGML editing system that satisfies our goals for structure, group authoring, and ease of use."