Leading Actuarial Solutions Firm Uses MadCap Flare to Achieve a 40-Fold Reduction in Documentation Production Time and Enable Single-source Publishing Across Multiple Print and Online Channels

Actuarial Resources Corporation (ARC) is a nationally recognized actuarial software and consulting firm dedicated to serving insurance institutions. Since 1987, the company has been delivering enterprise-level software solutions for life, annuity and health insurers anchored around its comprehensive ARCVAL financial analysis system. More recently, ARC began offering the Consolidated Actuarial Systems Environment (CASE), the platform for the next generation of the ARCVAL system, which simplifies and streamlines how information is managed.

To help its insurance industry customers take full advantage of the capabilities in ARCVAL and CASE, ARC delivers documentation both as online Help and PDF files using the single-source publishing capabilities of MadCap Flare. In the process, ARC has achieved more than a 40-fold reduction in the time that it takes to build its legacy documentation.

A Legacy of Duplication

For years, ARCVAL documentation was delivered once each year in a 3,700-page PDF, created in various source files from Microsoft^® Word, Microsoft^® PowerPoint^™, and the LaTeX documentation preparation system, among others.

“Using multiple source files often created minor inconsistencies that the human eye just wasn’t able to always catch,” recalled Matt Danda, ARC system documentation analyst. “Nearly 100 individual PDF files were created, and then the final PDF was produced by manually importing those files into Acrobat Pro, which caused additional issues. All told, it took 40 to 60 hours to create the final version.”

In addition to the PDF, online Help for ARCVAL was created in ForeHelp, but the ARC team found that it no longer supported the functionality they needed.

“The Help system was context sensitive at the screen level and contained thousands of field definitions,” Danda explained. “The Help system often contained duplicate and overlapping information found in the PDF that we couldn’t catch.”

Wanted: Single-source Approach to Documentation

The next-generation CASE platform, featuring a new architecture, was built using the agile software development methodology, and it was designed with the idea that updates would occur monthly. This would require all supporting documentation to be updated monthly as well. It quickly became clear that ARC would need a new approach to producing its online Help and guides.

ARC then zoned in on three main requirements for a new authoring tool. First, it needed to support a central repository for all source content, ensuring that this content would be easily accessible and that source files would never be lost. Second, it needed to provide single-source capabilities, so the same content could be reused in multiple forms of output, including configuration guides and the online Help system. Finally, it had to support industry-standard formats to provide flexibility in adapting to future requirements over the lifespan of CASE.

To address its requirements, ARC has turned to MadCap Flare with its topic-based authoring, ability to publish multiple types of output from the same project, capabilities for context-sensitive Help, and architecture based on industry-standard XML. ARC not only has created new content for CASE; the company also has migrated legacy ARCVAL documentation to Flare to simplify the management and publishing of existing content.

“The benefits of using Flare were immediately apparent, both in the ease of authoring and in the quality of the output,” Danda notes. “We expect that these benefits will only increase over time as more features are added to the CASE and ARCVAL systems, and the documentation set continues to grow.”

CASE: Fast, Multi-Channel Content Delivery

The initial release of CASE consisted of approximately 700 screens with 3,500 fields that all required documentation. However, the ARC team had an opportunity to design a new documentation structure while also leveraging content and experience from the legacy ARCVAL system.

With the future in mind, ARC’s writers set up the Flare project, designing an information architecture for the documentation set and creating an initial outline for each deliverable. Planning and configuring the backend structure of the Flare project included defining the folder structure, establishing file naming conventions, and creating a logical architecture for implementing context-sensitivity at the screen level.

In implementing the project, the writers followed structured authoring guidelines and created topics using the “concept/task/reference” topic-based authoring model. They also took advantage of several features in MadCap Flare to support content reuse and single sourcing, including variables, snippets and conditional text. Using Flare, they created page layouts for PDF output that replicated the look and feel of existing corporate templates. Additionally, the writers integrated Flare with Microsoft^® Team Foundation Server^® (TFS) to provide the documentation files the same level of protection and recoverability as the CASE source code.

The resulting documentation for the initial release of CASE features online Help and five guides delivered as PDF files. The online Help contains 1,000-plus topics, provides definitions for the fields displayed on all screens, and supports screen-level context sensitivity. Delivered as an HTML Help file, the online Help system also takes advantage of Flare’s single-sourcing capabilities and contains a variety of topics from the PDF guides. The PDFs include:

• A 123-page Installation Guide for network and database administrators.
• A 128-page User’s Guide describing essential tasks for using the CASE application.
• A 30-page Operations Guide covering advanced-level tasks for operating and maintaining CASE.
• A 176-page Financial Projections (GAAP) Guide with procedural and reference information.
• A 13-page CheckPFD Guide describing the utility required for legacy ARCVAL users preparing to upgrade to CASE.

“We were creating an entirely new set of documentation for CASE, so the initial project took a year and half to build,” Danda recalls. “However, the maintenance is very easy. Now we can build the online Help file in Flare, check the Help file into the CASE source code using TFS^®, and build the five PDF guides using the Batch Target in Flare, and the entire process can be completed in under an hour.”

Equally important is the modern, user-friendly experience that the CASE online Help provides. One of the popular features with ARC customers is the context-sensitive online Help available for more than 700 unique screens in the CASE platform, which was enabled by MadCap Flare.

Danda notes, “The CASE interface includes a Help button on every screen, and users have expressed to us that they’re very impressed with how they can simply click the Help button, and it sends them to the right page even though we have hundreds of topics.”

Migrating ARCVAL Legacy Documentation

CASE users also require access to certain legacy ARCVAL documentation. Therefore, ARC has migrated the legacy documentation to a MadCap Flare project as well.

“We wanted to preserve thousands of pages of our legacy ARCVAL documentation that was relevant to our CASE users and these still needed to be maintained,” Danda explained. “However, all of our legacy documentation was stored in a format that was becoming too labor intensive to update. Flare really checked off the boxes on our list.”

The original ARCVAL documentation spanned 3,700 pages and was divided into 13 chapters that each described a separate module of the ARCVAL system. To start, ARC’s writers created a new Flare project for the ARCVAL system documentation. Each chapter, or module, from the original documentation was recreated as a separate PDF target, and within each chapter, the content followed a structure similar to the original documentation.

The process of importing content varied slightly depending on the type of information being imported.

Some content, such as conceptual descriptions and process flow diagrams, imported easily. Much more difficult to migrate were some 100 Word files formatted almost entirely in tables that produced 2,000 pages of content.

“Our old process for assembling the PDFs into one customer-ready PDF of the ARCVAL system documentation used to take 40 to 60 hours, and we only produced it once a year,” Danda explains. “Now using Flare, we can produce an updated version of the documentation on demand as updates are released, and we can build it in about an hour.”

Simplified Document Development, Design and Integration

ARC takes advantage of many additional features in MadCap Flare to facilitate content design and development, including cascading style sheets (CSS), the XML editor, and file tagging.

“I really like that MadCap Flare supports CSS,” Danda says, “My PDF output isn’t an exact copy, but it looks so much like the operable Word template that it’s really hard to tell the difference. I’m able to do that because of CSS templates. When I want to tweak the style, I can pull out a regular CSS book and find the right commands.”

The fact that MadCap Flare is based on XML and includes a built-in XML editor also helps ARC to simplify document maintenance.

“Because Flare is based on XML and separates content from presentation, if I need to make a quick edit to existing content, I can find the relevant topic in Content Explorer and make the change in the XML editor,” Danda observes. “In the past, the same process required additional time and effort due to the complexities inherent in working with very large Word documents.”

Meanwhile, to handle the 700-plus topics in the CASE Help system, ARC writers have used MadCap Flare to create a system for tracking work-in-progress and producing status reports. It consists of a series of file tags in Flare that reflect the type of information with a topic and whether it is complete. When working on a topic, the writer selects the appropriate file tags from the topic properties window in Flare.

”We have hundreds and hundreds of topics to keep track of. I can simply create a follow-up tag and tag topics with their status of completion,” Danda notes. “Through file tagging, Flare has made it really easy to track my progress, and at the end of the year, I was able to give management a report with the exact number of topics I had completed.”

Fostering Collaboration

MadCap Flare’s integration with Microsoft^® TFS^®, not only makes it easy to check the source documentation files into the platform’s source code; it also facilitates collaboration among ARC team members.

“Our team uses TFS^® to create a system for tracking work items during each sprint, and I can easily integrate my latest output into the code builds. We are able to see how our content is converged. I like the fact that Flare handles the checking in and out of the source content in TFS^® with one simple click of a button,” Danda explains.

Additionally, the Word integration functionality in Flare makes it easy for subject matter experts (SMEs) to contribute content.

“Our SMEs will write content in Word or create it in an email, and then I’ll generate it in Flare,” Danda says adding, “Any new content I write in Flare.”

In addition to MadCap Flare’s functionality, ARC also takes advantage of MadCap support and forums, Danda observes: “I don’t call often, but one time I had a very obscure issue with an output file. I was surprised and impressed when MadCap’s support team found the solution. Another time I had a fairly obscure problem with auto-numbering; I was able to get an answer from the MadCap forum and fix it.”

Looking Ahead

With the MadCap Flare-based CASE and ARCVAL documentation projects in production, ARC writers are looking at how to enhance content development and maintenance. One area of particular interest is taking advantage of MadCap Flare’s standard XML architecture to automate the creation of hyperlinks.

“We have massive record layouts described in tables with hundreds of rows. In a separate chapter we have definitions of those rows,” explains Mr. Danda. “I want to create XML that automatically creates hyperlinks across these. For example, a particular row has its own definition. I can do the hyperlink manually, but when you have to do thousands and thousands of rows, it creates a real challenge. Currently, we are still in the beginning stages of this project.”

Mr. Danda adds, “Adopting MadCap Flare has allowed us to develop a new content management system that is providing us benefits today with an improved customer experience, high quality output, and greater productivity. As we continue to develop and maintain our CASE and ARCVAL documentation in Flare, we only expect these benefits to increase over time.”