Synergex Speeds Development and Delivery of Interactive, HTML5-Based Technical Documentation with MadCap Flare

For more than 40 years, Synergex technologies have been at the foundation of many applications that drive commerce around the world. In fact, millions of users interact daily with systems in e-commerce, global logistics, manufacturing, healthcare, and other industries that are built on or managed by Synergex solutions.

Synergex’s flagship product is Synergy/DE, a portable, scalable framework that powers software applications worldwide, from small shops to Fortune 100 corporations. The full suite of application development tools is built around Synergy DBL, a proven business language based on ANSI-standard DIBOL. Also included in the suite are a high-performance indexed database, connectivity tools for remote data and application access, and integration with Visual Studio.

To ensure that users are able to maximize their use of their product suite’s capabilities, Synergex delivers responsive HTML5-based technical documentation that makes it easy for customers to find the information they need. Today, the company relies on the topic-based publishing capabilities of MadCap Flare to produce responsive web content, which automatically adapts to users’ different screens, from desktops to mobile devices.

Rethinking Approach to Content Delivery

In the past, Synergex distributed documentation in two formats. The company created PDFs using Adobe^® FrameMaker^® and Adobe^® Acrobat^®, and also used Mif2Go, a FrameMaker^® plugin, to convert Frame files into HTML for web-based documentation. Over time, however, the technical writing team found the conversion process to be time-consuming and complicated. Additionally, the web-based content lacked visual appeal, wasn’t responsive, and wasn’t optimized for online viewing. Recognizing the need to revamp its documentation, the company surveyed key customers, and then the writers held a doc summit that included internal stakeholders to get feedback.

“The general feeling was that we needed to modernize the documentation as well as streamline our processes to make it easier to produce,” recalled Matt Linder, senior information developer at Synergex. “We decided that it made sense to focus primarily on online documentation rather than PDF, and that we’d need a more robust solution to support that move, instead of continuing with the Mif2Go conversion process.”

Synergex’s search for new software quickly zeroed in on MadCap Flare. Flare emerged as the clear choice because it provided the advanced capabilities Synergex needed to produce modern web content while enabling the team to publish updates more frequently to keep pace with product changes.

“Flare was just much more modern and forward-looking than other products we considered, with advanced CSS features,” Linder explained. “In addition, MadCap’s technical support during the evaluation period was very responsive.”

Linda Kelley, senior information developer at Synergex, added, “We were able to generate professional-looking documentation out of the box, which enabled us to get started quickly, since the design was already built into what you get from Flare.”

Flare’s XML Architecture Facilitates Conversion Process

As Synergex started planning for the conversion of over 200 legacy files, the technical writers realized that the migration process would be difficult due to the complexity of the existing documentation. “We had hundreds of cross-manual links, which weren’t easy to preserve, and complex formatting that worked well in FrameMaker^®, but didn’t translate easily to HTML,” Linder said. “We had to think long and hard about how to convert the files and preserve the links.”

While Synergex’s technical writers weren’t able to use Flare’s built-in FrameMaker^®-to-Flare conversion tool, they took advantage of Flare’s native XML architecture to develop their own conversion program using C# and HTML Agility Pack, an HTML parser from open source package manager NuGet. The final process involved converting the Frame files to HTML with Mif2Go, then using a custom conversion program to clean up the files and add tags necessary for Flare.

“The fact that Flare’s architecture is based on open standards made it feasible for us to write a conversion program,” Linder observed. “Since Flare files are in an XML format, we were able to use HTML Agility Pack to write code to deal with the tags and clean things up.”

Also contributing to the conversion effort was the team’s use of MadCap Analyzer. Synergex writers used MadCap Analyzer to find critical issues in the documentation, such as broken hyperlinks or topics that were not included in the table of contents (TOC).

“MadCap Analyzer helped us to identify what needed to be done in our conversion program,” Linder noted.

Timely Publishing via MadCap Flare

Today, Synergex’s technical writers provide customers with an HTML5-based documentation website that is integrated into the company’s corporate website. It contains interactive, technical documentation—both converted content and new content created using MadCap Flare—for Synergex’s Synergy DBL language and the tools built around it. To speed the creation and publication of this documentation, the team takes advantage of topic-based authoring features, condition tags, TOCs, and variables in MadCap Flare.

“Flare’s topic-based authoring has enabled us to modernize our authoring approach from the traditional, linear book format of FrameMaker^®, which wasn’t as effective for producing online outputs,” explained Linder.

Kelley added, “Being able to create smaller, more discreet topics in Flare has added a new level of flexibility and reusability that we didn’t have before. We’ve also been able to give our documentation a cleaner look and feel.”

The writers use variables in MadCap Flare for product names and use condition tags to mark passages and topics that have yet to be published as well as to mark text about features that are only available in limited-release versions of some of the products.

“Flare’s condition tags enable us to automate updates to align with product changes or releases,” Linder said. “We can now turn content around much faster and facilitate more frequent updates. In the past when software was released, it took us at least two weeks to generate and publish the online version of the doc. Now, with Flare, we can quickly build the latest documentation version.”

Fostering Collaboration with Apache SVN Integration

To assist with collaboration and source control, Synergex relies on MadCap Flare’s integration with Apache Subversion (SVN). This integration has helped the technical writing team to better manage, archive, and share content as well as adhere to the company’s disaster recovery policies, and it makes it easier for the writers to collaborate despite working from different locations.

“With our old system, it wasn’t feasible to integrate with source control, so we really appreciate the fact that Flare supports Apache SVN integration,” Linder said. “Being able to include our doc sources in the repository that we use for our software is really convenient. When our developers back up their code, our content is automatically backed up as well; we no longer have to do it separately.”

Optimized User Interface

In addition to improving the technical writers’ efficiency, Flare has helped to enhance the customer experience for Synergex users through such features as responsive design, enhanced search functionality, and browse sequences.

“Flare’s HTML5 responsive design has helped us achieve our goal of providing a more intuitive, professional-looking, and streamlined user interface,” Linder noted. “It’s great that customers get the same optimized view regardless of the device they use.”

Kelley added, “People like the new design we’ve created with Flare. Since our Synergy DBL programming language is one of the most portable languages, it’s nice to say that our documentation is portable, too.”

Meanwhile, Flare’s search bar—where users can type in terms to find what they need—makes it fast and easy to navigate the content. The Synergex team has also added an errors tab using the browse sequence functionality in Flare.

“With our old online format, when customers got error messages, they had trouble locating the actual errors and finding out what the messages meant,” Linder said. “Thanks to Flare’s browse sequence functionality, we were able to innovate a solution that makes it easy for users to look up an error and figure out how to solve the problem.”

Kelley concluded, “Overall, our new documentation is much more contemporary and accessible, and it delivers a far superior customer experience. This wouldn’t have been possible without Flare.”