Managing Complex Online Information Systems


August 2001

Managing Complex Online Information Systems

CIDMIconNewsletter David Walske, Content Management Consultant

In early 1999, Symantec Corporation began developing the Symantec System Center as a snap-in to the Microsoft Management Console (MMC). One of the requirements for MMC snap-ins is compiled Microsoft HTML Help. While Symantec had long been an industry leader in the use of HTML-based user interfaces, the software company had yet to release a product with compiled HTML Help. The Information Development team viewed this as a unique opportunity to set a new standard for online help. A committee, composed of documentation managers, editors, and writers from diverse project areas, was formed to establish an HTML Help standard for Symantec.

I was asked to join the HTML Help standards committee as an independent consultant and to lead the help development effort for the Symantec System Center. These two parallel functions produced great synergy of effort. The weekly prototypes from my production work provided stimulus for the standards committee, while the weekly reviews from the standards committee provided guidance for my design and information-architecture work.

The help system that resulted was well received by customers and peers alike, winning customer praise as well as awards and recognition from experts in the online help development field. A new challenge lay ahead. This help system was produced in the rarefied environment of a prototyping project. A variety of tools and complex technologies were used without consideration of the needs of help authors working in the production environment. If the Symantec System Center Help was to become the standard for all HTML Help at Symantec, production processes needed to be streamlined and simplified. Content developers needed to be able to concentrate on issues of domain knowledge and good writing, not the complexities of help code.

With the Grace of a Swan

There are few more graceful sights than that of a swan gliding effortlessly across the water. This delightful image expresses the ideal experience of the help user. Usable design and viable information architecture promote this kind of end-user experience. Unfortunately the user experience is often much different. Many online help systems use an information architecture that segregates conceptual and procedural information. To cross-reference between related information of different types, users are often required to use high-level navigation tools such as the Table of Contents or Index.

This non-integrated approach to the organization of information types reduces usability by creating a disassociation similar to the “split attention effect” described by the cognitive load theory of John Chandler and John Sweller of the University of New South Wales. While completing a procedure, users often need related conceptual information in order to make an informed choice at one or more of the procedural steps. If related conceptual information is not easily accessible, users are distracted from the primary task at hand by the often cumbersome and inexact task of retrieving such information. With a little luck, the user retrieves and assimilates the necessary conceptual information but in the process has disassociated from the specific procedural step that sent him looking for conceptual support in the first place. If you have ever assembled a bicycle, or anything in kit form for that matter, you have already experienced disassociation first hand.

How then do you avoid disassociation? Simply combining both information types in help topics isn’t the complete answer. Topics become long and confusing. Users must often scroll significantly to find content and in some cases may even fail to find some information located at the end of very long topics.

Topic organization
To avoid clutter, confusion, and excess scrolling, the Symantec Help design employs three collapsible sections. At any given time, only one of three information types-conceptual, procedural, or relational-is displayed (see figure below). Clickable headings allow users to open and close the sections, moving effortlessly between information of three distinct types, all pertaining to the single subject of the individual help topic. To provide further ease of navigation, a set of clickable folder icons displays in a non-scrolling area in the upper left corner of the topic pane. These folders, identified as About, How To, and More Info, provide persistent visual clues about the type of information currently displayed without intruding on the user experience.


Collapsible Sections

The truth about swans
In this perfect vision of integrated, organized, and subject-centric information, the user interface (UI) is all but transparent to the help user. It doesn’t announce itself boldly, demanding attention. It is quiet and serene like the gliding swan.

You’d never suspect it, but below the water line, hidden from the world above, the swan paddles wildly and with furious intensity. This also is the picture of Symantec HTML Help. Unbeknownst to the help user, a cacophonous mix of HTML, DHTML, JavaScript, and ActiveX technologies are at work beneath a serene UI.

Streamline or Perish

No matter how masterful, any help design that is impossible to deploy in a production environment will suffer a premature demise. The ever-quickening pace of software-development demands help development processes that are streamlined, efficient, and responsive to change. Workflow must be shielded from the complexities of the underlying help system technology. The last thing a project manger wants to hear on the phone at 3:00 am is, “The help system broke the build.” And, the last thing a writer needs to hear is, “How much do you know about JavaScript?” If the complexity of the code is exposed at either of these vulnerable points, the help design will soon be replaced by something easier to deploy.

Repurposing tools
About the time that Symantec HTML Help was about to enter mainstream production, Symantec began stepping up its existing drive to increase content reuse through repurposing. Repurposing allows content created for one output format-usually print-to be reused in another output format such as online help. An effort was underway to manually map and synchronize elements of information between print and online documentation. This proved to be an arduous and time-consuming task. Independent of this effort, I had begun to explore custom WebWorks Publisher Professional templates for use in the automated creation of Symantec HTML Help source code.

WebWorks Publisher-a product of Quadralay Software-converts Adobe FrameMaker documents into various online formats, including compiled HTML Help. Using the supplied generic templates, it is possible to begin porting FrameMaker documents to standard compiled HTML Help in less than thirty minutes. Using WebWorks Publisher to create more complex help systems such as Symantec HTML Help requires the development of custom templates. By investing the time and effort required to build a complex custom WebWorks Publisher template, Symantec was able to fulfill the goal of shielding workflow from the complexity of the underlying code while enhancing reuse by repurposing content from print to online.

Symantec HTML Help template
The custom WebWorks Publisher template for Symantec HTML Help uses a combination of WebWorks macros and regular expressions to port and manipulate FrameMaker content. Macros perform most of the conversions, while regular expression processing provides advanced search-and-replace technology for further manipulation of content in the online help.

FrameMaker print projects are typically organized as a series of files, each corresponding to a single chapter, collected into a FrameMaker Book file. The Book file has no content of its own but rather is a container for the chapter files and a tool for automatically generating Table of Contents and Index files. WebWorks Publisher leverages these automatically generated files, converting them into the source code for the compiled HTML Help Table of Contents and Index.

Topic breaks
Specific FrameMaker paragraph styles signal WebWorks Publisher to break to a new topic file during content conversion processing. The Symantec HTML Help custom template breaks at each of the three heading levels allowed by Symantec editorial standards. Each FrameMaker heading and all of the content that follows it up to, but not including, the next heading can be thought of as a heading group. Each heading group is converted to a single help topic.

To accomplish heading-induced topic breaks, FrameMaker paragraph styles are mapped to WebWorks Publisher designer styles prior to conversion processing (see below). To support the Symantec HTML Help design, all of the heading levels must be mapped to break to a new topic. All paragraph styles are mapped to an appropriate WebWorks Publisher designer style, although in some cases that style might create no output. The No Output designer style is useful for eliminating content that should never appear online.


Style Conversion

Section breaks
Creating the three distinct About, How To, and More Info sections of Symantec HTML Help requires a combination of macro and regular expression processing. Step-intro paragraph tags indicate the beginning of procedural information in the FrameMaker document. These are mapped to a custom WebWorks Publisher designer style that contains the DHTML and JavaScript code necessary to create the How To section. Because some heading groups produce topics that do not have procedural content, additional regular expression processing alters the help code output when there is no step-intro paragraph in a particular heading group. This procedure creates a help topic in which the How To folder graphic in the non-scrolling region of the topic is appropriately dimmed.

The clickable headings are created from FrameMaker content through the use of macro and regular expression processing. For instance, in a heading group titled “Scanning for viruses,” the text of the title would appear as normal in the help topic and would also be processed to appear as “About scanning for viruses” to create the clickable heading for the About section. This same heading group might contain a step-intro paragraph such as “To scan for viruses.” This content would appear as normal in the help topic introducing the procedure to follow and would also be processed to appear as “How to scan your disk” to create the clickable heading for the How To section.

The content of the more-information section is generated automatically based on the hierarchy of the help topics. Author-supplied cross-reference information contained in FrameMaker document text is also converted into related information links.

Quality Assurance Issues

Manually created source code of any kind contains errors. Human beings cannot reliably generate flawless code. This inherent faultiness of manually created code requires repeated rounds of Quality Assurance (QA) testing and bug fixing. Each time a software engineer updates or alters source code in any way, a QA process is necessary. Automatically created help source code is no different.

When help source code is automatically generated using WebWorks Publisher, many of the requisite rounds of QA may be eliminated. Once the help code is certified bug free, generating new code from the same set of FrameMaker files to incorporate content changes is relatively risk-free compared to the risky act of manual code modification.

This testing issue is one to be negotiated with QA teams after significant testing. But in general, automated source code generation inspires confidence in code quality that can significantly reduce the QA load for help projects.

Good Design Deserves Best Practice

By relieving the help author of the task of tedious and complex coding, the custom Symantec HTML Help WebWorks Publisher template has helped Symantec Information Development focus on the quality of writing, the quality of information, and quick turn-around time. It has also reduced the QA load and has increased content reuse.

These practices concentrate on moving the difficult, time consuming, and risky tasks away from the authoring side of the process. By front-loading this overhead to a technology-development team, significant economies are achieved that result in providing a better quality product at a lower overall cost.

About the Author