Strategies and lessons learned from developing an intranet with FrameMaker and WebWorks Publisher.

B Y  J E A N - L U C   M A Z E T    &    M A T T H E W   R E E V E S
Austin Chapter



Across the industry, there's a lot of talk about single-source documentation: the pros and cons; recommended tools and workarounds; and the realities of effectively delivering online and paper content from a single source. It makes sense for writers to maintain only one set of content while paper and online users benefit from exactly the same information. And it's essential to customize the paper and online formats individually to ensure usability. It is a tall order, but it can be done.

In April 1999, we made these goals a reality for the content of 19 reference manuals containing more than 8,000 pages. Adobe FrameMaker and Quadralay® WebWorks® Publisher were the main tools we used to develop and maintain the single-source documentation. Each month the updated content of the reference material is pushed from the printed page to the intranet/extranet documentation system we call e-OPM, which stands for electronic Operations and Procedures Manual. About 700 EDS and state agency users rely on the information to complete their claims processing work.

We were determined to make the single-source strategies work well. Almost two years after beginning the project, this Hyperviews:Online article is an opportunity to share experiences, strategies, and lessons learned.


The "Butterfly Challenge"

The "Butterfly Challenge" was to supply over 700 customer service representatives, claims processors, and claims auditors with up-to-date health care policies and billing procedures.

Until April 1999, the challenge had long been handled using a paper-based system known as the "butterfly." Each customer service representative and claims processor maintained individual butterflies containing more than 8,000 pages.

Project goals

We had several project goals:

  • Team up with 25 content experts to improve the access and usability of information.
  • Remove the maintenance burden from the front lines.
  • Affect long-term productivity strides.

We also decided that we had one main priority to help achieve these project goals -- to provide consistent, user-friendly documentation from a single source. We wanted our people and customers to work and benefit from exactly the same information. The solution had to enable provider claims and inquiries to be handled from a single source of information, improve format and consistency, and reduce the number of production errors caused by outdated documentation.

Solution The content is maintained in 19 FrameMaker 5.5.6 book files that make up the paper version of the Operations and Procedures Manual. Each FrameMaker book file is linked to a WebWorks Publisher project (.wdt). Through a .wdt, WebWorks converts FrameMaker files into HTML files, generated graphics, and specified macros. WebWorks provides functionality that enables the mapping of virtually every FrameMaker attribute including paragraph, character, table, marker, cross-reference, and conditional text tags. The WebWorks output tag mimics the functionality of a FrameMaker master page so that HTML can be generated with particular boilerplate text and graphics on particular HTML pages.

We developed customized .wdt templates using building blocks and user macros available in WebWorks. The customization enabled generation of HTML files coded with hyperlinks, JavaScript code, and common elements between book files and to the e-OPM interface files. All 60,000+ intranet files are housed within a single directory with a given subdirectory hierarchy that allows relative hyperlinks and no hard-coded links ("http://").

On top of e-OPM's HTML interface and the thousands of HTML files generated from the FrameMaker source is a search engine, Infoseek's Ultraseek 3.1. Twenty-five paper libraries of the Operations and Procedures Manual are maintained as a backup system in case the Web site is down. Users also can access Adobe® Acrobat® files (.PDF) on the LAN as another backup.

At the same time each month, the OPM paper libraries and the e-OPM are updated monthly with the latest policy and procedure information.

Even though the paper and web documents are produced from a single source, the e-OPM solution enables the output to be customized for two mediums: paper and online. In other words, careful template planning and coding yields output designed specifically for paper and web consumption.

Solution at a glance

Project definition

The first step was understanding the challenges faced by users and how electronic documentation could improve productivity. Under the direction of the project manager, Kim Day, we set out to achieve this by establishing user groups with a cross-section of representatives from the claims processing and customer environment.

We met with the user groups on a weekly basis to identify the elements of the documentation critical to work processes and how users applied the information. Two months into the investigation, the development team began analyzing the information collected and then developed prototypes for user group review. Two prototypes, paper and web-based, were developed for each of the reference manuals.

The paper prototypes were created using a FrameMaker book file including the table of contents, index, chapter, and list of paragraph files. The web-based prototypes were created using customized WebWorks Publisher projects (.wdt) linked to the FrameMaker files. The HTML files generated through the .wdt included the paper-based book elements organized for online consumption. The development team continued to improve the paper and web-based output until final user group approval was received. All development team solutions were tied directly to user requirements and preferences.

Sample e-OPM web page prototypes

The FrameMaker files created for the prototypes became the backbone of the solution. In the end, documentation content is maintained in FrameMaker files only and the interface files are updated through straight HTML coding.

On Dec. 2, 1998, the first official paper copy of the Operations and Procedures Manual (OPM) was delivered to the state of Texas.

Meanwhile, development of what was to become e-OPM continued. Mazet developed the web architecture for the e-OPM interface. The interface became the user's entry point to thousands of valuable documents. Ultimately, the interface files provided users with an electronic reference system that enabled them to proactively access and research essential policy and procedure changes.

In addition, Mazet customized the Infoseek Ultraseek search engine users access through the e-OPM interface. Mazet set up the search engine to enable users to query across all e-OPM files, files on e-OPM during the current month, and the files of past e-OPM months archived on a monthly basis. The search design also allowed the user to limit query results to one or multiple e-OPM book files.

Current e-OPM - home and search pages

The next step was to launch the e-OPM Pilot Program to test the solutions implemented. Reeves developed the pilot program and training curriculum. About 50 EDS/NHIC and state agency users participated in the pilot. Novice, intermediate, and advanced business experts from all departments tested the first version of e-OPM.

The pilot program was rolled out to the users at a training seminar in January 1999. Each pilot participant received a seven-day workbook for e-OPM testing. The workbook provided tips, activities, questions, and a journal for each day of testing. The developers ran a daily e-OPM help desk to support the testers and to document bugs reported. At the end of the pilot, employees from our Quality Services Division collected the workbooks and the conclusion evaluation forms. From the workbooks and other evaluation materials, this group documented testing results and culled user experience feedback.


It was time for us to interpret the feedback so the tool could be improved before its release. The developers created an implementation document from the pilot findings that helped management prioritize change requests and enhancements. Priority one items were incorporated before account-wide training, and priority two items were delayed until after implementation.

As a result, an improved e-OPM intranet was the basis of NHIC and customer training classes held in March 1999. The training curriculum included:

  • Web and Windows® terminology
  • e-OPM basics (connection, navigation, archives, e-Help)
  • e-OPM advanced features (search engine)

On April 2, 1999, the project team implemented e-OPM, an intranet/extranet site with over 8,000 pages generated and maintained from a single source. The e-OPM intranet was implemented successfully for over 700 users.

The support of the site started the same day as the implementation. It included an e-mail address for e-OPM bug reports, a list of subject matter experts (SMEs) on the site's FAQ page, and a help desk for technical issues such as connection or computer setup.

End user benefits

The single-source intranet/extranet documentation enables users to:

  • Learn how to use the site through help topics in e-Help.
  • Search across all or selected electronic books for current and archived information.
  • Open with a single click the claims processing rules associated with a particular medical policy.
  • Open all updated web pages (for the month) from a single location.
  • Identify changed policies and procedures instantly through red flag and text indicating updated content.
  • Conduct research in electronic provider manuals and instantly open related bulletin updates.
  • Access monthly archived content to handle issues subject to earlier policy and procedure.
  • Submit FAQs and intranet/extranet feedback.
Implementation success measurements We measure the success of the single-source intranet/extranet implementation with the following statistics:
  • Average length of user session is 14:59 minutes.
  • Site receives about 5,000 hits and 800 search queries per day.
  • All EDS/NHIC departments recycled their paper copies and are now using e-OPM 100 percent.
Lessons learned

We learned the following lessons:

  • Aggressively pursue and listen to your users, study their work habits, and test your prototypes with them in a real-life environment.
  • Organize user needs into two categories: paper and online. Your main focus should be paper because you can customize your print styles for HTML output.
  • Choose an HTML generator (e.g. WebWorks Publisher) that allows you to mold and customize the information on your site (e.g. split HTML files on specific headings, create user macros for locators on the web page, JavaScript "Next" and "Previous" page).
  • Use conditional text to hide content only applicable to paper or PDF. Place all graphic items into anchored frames. Test your spacing once converted to HTML (e.g. tables, lists).
  • Plan carefully by defining your file and web interface hierarchy.
  • Implement a content source control tool for document management and use version control and version archiving for all your files.
  • Take advantage of building blocks and boiler plate text to facilitate future maintenance.
  • Save graphics embedded or imported into FrameMaker as PDFs and use a "Hypertext" marker to reference them. The PDF maintains the full integrity of the image (e.g. claim forms).
  • Stress test your web server to make sure it can handle expected user traffic. Always allow room for growth.
  • Prepare your site security using SSL or other protocols. You do not want a "hacker" to access your site and start changing your content.
  • Test your site with all available browsers and versions. This is especially important if you are going to post your files to the Internet.
  • Test from all possible points of entry (e.g. extranets, intranets, dial-up connections).
  • Invest in a good search engine.
  • Look into link verifying software. It is difficult to check 100,000 links manually.


Coding, tools, and hardware information
  • HTML 3.2 and 4.0
  • DHTML and JavaScript
  • Active Server Pages (ASP)
  • Python (for the search engine)
  • Adobe FrameMaker 5.5.6
  • Adobe Illustrator 7.0
  • Adobe PhotoShop 4.0.1
  • Web Works Publisher 4.5 and 2000
  • Adobe Acrobat Suite 3.0
  • Infoseek Ultraseek 3.1 search engine
  • Linkbotpro 4.1
  • Allaire HomeSite 4.0.1 and 4.5
Server-side hardware
  • Compaq 3000 server with redundant server and LocalDirector load balancer
User-side hardware
  • Dell or Gateway workstations (233-450 MHz)
Server-side software
  • Internet Information Server 4.0
  • Infoseek Ultraseek Server 3.1
  • Index Server
User-side software
  • Internet Explorer 4.0 (recommended) and higher
  • Netscape Communicator 4.0 and higher
  • Adobe Acrobat Reader 3.0 and higher
Trademarks All other proprietary names or information contained herein are the properties of their respective owners.
Return to Home Page

Jean-Luc Mazet and Matthew Reeves are EDS/NHIC information designers who were charged with developing an online documentation system in 1998 for the National Heritage Insurance Company (NHIC). NHIC, a subsidiary of EDS, serves as claims administrator for the Texas Medicaid program and several other state health care programs under contract with the Texas Department of Health (TDH). Each year, EDS/NHIC employees process over 33.5 million health insurance claims and answer over 400,000 customer service calls related to claims processing.

Winter 2000
Volume 3, # 1