Illumio Chooses MadCap Flare to Deliver Modern Documentation Website in Less Than One-Fourth the Time

When the world’s leading organizations need to protect their critical data, they turn to Illumio to stop breaches from becoming cyber disasters. A pioneer and market leader in zero trust segmentation, the Illumio platform provides holistic visibility into security risks and automates policy enforcement to stop cyberattacks and ransomware from spreading across applications, containers, clouds, data centers, and endpoints.

To ensure that customers can fully leverage all the capabilities of the Illumio product portfolio, the company maintains a modern, responsive documentation website with two HTML5-based product guide portals and a range of downloadable PDFs. Since migrating from Atlassian Confluence, Illumio now produces this content using MadCap Flare to ensure a modern web design and maximum content reuse while easily publishing content to multiple channels — all from a single source.

Outdated Documentation for State-of-the-Art Software

For years, Illumio relied on its original content authoring system to develop guides for its industry-leading Illumio Core and Illumio Edge products and then export the content into HTML and PDF formats that were posted on the company’s internal support site. However, the long scrolling pages had almost no formatting, making it difficult for customers and employees to find the information they needed.

“The content produced with our previous platform was not modern at all, and we knew we needed to provide a better experience for our customers,” recalled Katherine Morgan, director of technical publications at Illumio.

Moreover, every guide was separate and siloed, adding complexity and redundancy any time a new or updated guide needed to be produced.

“The last three days to get the release out were becoming harder and harder, and we started to realize that if we didn’t find a better solution, we couldn’t continue to deliver the documentation on time,” Katherine explained. “That realization led to our team getting the greenlight to look at other products.”

Illumio considered whether to work with an open standard, such as the Darwin Information Typing Architecture (DITA) XML data model for producing technical information and the easy-to-use Markdown markup language. Additionally, the company looked at a range of commercial products, including MadCap Flare.

“I had a lot of questions, so I went to the MadWorld user conference to learn more about Flare,” Katherine said. “After attending several talks and getting a tremendous amount of information, I realized that MadCap Flare would give us the features and user experience we wanted at a reasonable price point that was significantly lower than implementing DITA.”

Developing a Modern Web Design

A top priority for Illumio was creating a modern web experience for customers using its guides, which aligned with the company’s corporate website, so the company took advantage of the resources and best-practices examples available for MadCap Flare.

As a first step, the technical publications team chose the MadCap Flare Balboa and Coronado templates to serve as the basis for designing their own documentation web portals. They then reviewed many of the companies highlighted in MadCap Software’s Customer Showcase to identify the website functions and behaviors they wanted to incorporate. Next, they brought on a certified MadCap Software consultant to implement the documentation portal design.

“We could have created the documentation site design ourselves. However, a MadCap Software consultant was able to deliver a working prototype of our design based on the two templates in fairly quick order. He was amazing and very collaborative,” Katherine recalled.

The technical documentation team then reskinned the working prototype to align with the corporate branding and built the cascading stylesheets (CSS) using the skins and CSS editor built into MadCap Flare.

“Using Flare’s skins and CSS editor, I was able to get the look of our documentation sites really close to the look of our company website and get the marketing team’s sign-off,” Katherine said.

Using the approved prototype, Illumio’s technical documentation team produced two documentation portals: one for Illumio Core and another for Illumio Edge. The company then had its existing guides imported into the new portals. Meanwhile Illumio’s technical writers began using MadCap Flare to develop guides for the newest versions of the products.

“Using Flare, we were able to design the portals, create custom user actions, and get them up and running,” Katherine noted. “People have been astounded.”

Creating an Intuitive User Experience for all Outputs

Today, Illumio maintains a documentation website with two portals, one for each of its main product lines, which each provide guides for four to five product versions. The guides can be viewed as responsive HTML5 content that adjusts to users’ desktop and mobile screens or downloaded as PDF files to view offline.

“Software companies are moving from PDFs to an HTML5 web experience, so I wanted our focus to be on having an HTML5-based website with intuitive top navigation. At the same time, we’re in security, so some of our customers can’t just get on the Internet; they need PDFs. We also get a lot of demand for PDFs from our sales team,” Katherine explained. “With Flare, we’ve created each portal as a central source where the HTML5 content and PDFs for each guide are dynamically linked. When users look at the HTML5 guide, they see an icon for the PDF to download.”

Unlike the guides produced on the previous documentation publishing platform, where there was a continuous scroll of content, Illumio takes advantage of the topic-based authoring in MadCap Flare to organize information into easy-to-navigate sections. Additionally, the company relies on the search functionality in MadCap Flare to help customers quickly find the information they need.

“Flare's built-in search engine works well for us. We briefly considered trying Google search, but then we would have lost some of the advanced features we get with Flare, like micro content,” Katherine said. “We particularly love Flare’s search filters, which help us to search just the area of a guide that we want. Our customers regularly use these filters, too.”

To further simplify navigation, Illumio has added selectors to a dashboard on the home page of the documentation website. From there, customers can pick which product line and which version they want to go to.

“The selectors on our dashboard are one more way we’re using Flare to make it easy for customers to quickly find the product information they need,” Katherine notes.

Speeding Content Delivery

In the past, producing a product guide was a difficult and time-consuming process for Illumio. The documentation team had to generate the HTML first, then produce the PDF, then package everything up, drag the content into a directory, run a script, and finally publish it. Additionally, Illumio’s previous authoring platform didn’t support a quality control process, so the team had to put the guides in staging and scroll through them line by line to visually identify any issues, such as broken images or bad URLs.

Now the team takes advantage of the Analytics functionality in MadCap Flare to automatically check for issues—such as broken images, broken links, bad formatting, and ugly tables—as well as make recommendations on how to correct or improve them.

“It used to take four team members up to 10 hours a day to publish a guide for a new product release, up to 40 hours total,” Katherine explained. “Now a single technical writer at Illumio can use MadCap Flare to handle the entire guide creation and update and push it out on the portal all in an afternoon.”

Katherine added, “We’ve also seen a huge jump in the quality of our guides, since we use Flare to find and fix any problems before they get published. I also love the builds because I can look at the logs and easily troubleshoot any issues.”

Simplifying Version Control

By leveraging MadCap Flare’s integration with the Git version control system, Illumio has been able to simplify the process of committing content.

“I like being able to do everything with Git from within the Flare user interface,” Katherine notes. “Flare prompts us with commands like, ‘You need to pull’ or ‘You need to push,’ so we rarely get conflicts with our commits to Git. That’s a key feature for us.”

Illumio made a strategic decision to have multiple guide projects that different writers would work on. To ensure consistency and eliminate redundant work, the company relies on the Global Project Linking feature in MadCap Software. For each of the two products, the technical documentation team maintains a global project, a build project, and then all of the separate guide projects.

“Flare’s Global Project Linking is a life saver,” Katherine says. “To produce a guide for a new product release, we just create a new branch. It’s the only way we can produce all the guides that we do and meet the release deadlines.”

Modern Product Guides Now Gain Wide Use Across Sales, Marketing and Product Management

The MadCap Flare-based product guides were designed to improve customers’ experiences, but they have since become widely used across the company. Sales representatives will request changes to topics to support a proof of concept for a customer, and they have started requesting that other company content, including marketing collateral, be added to the documentation website for easier access.

At the same time, the technical documentation team is seeing demand from product managers tasked with enabling integrations between Illumio’s products and those of other vendors using an API provided by Illumio. Now the website includes documentation on the APIs that is searchable and easy to find, facilitating the integrations.

“It's been a night and day experience since we rolled out our modern documentation website using Flare. It went from something no one really thought about to a resource that’s considered indispensable,” Katherine observes. “Now we have modern web-based documentation that anyone can access—employees, customers, analysts, prospects and others—and demand is skyrocketing.”

What’s Next

Looking ahead, the technical documentation team plans to use MadCap Central for cloud-based collaboration with the company’s subject matter experts (SMEs).

“MadCap Central is on our roadmap,” Katherine explains. “We like the idea of using it to let our SMEs review guides in real time and make basic edits. That would save us a lot of time.”