Product Groups Across Perforce Software Rely on MadCap Software to Drive Innovation in Modern Online Help, Documentation, and Translation

Whether building, testing or managing applications, more than 20,000 enterprise customers and 1 million-plus users worldwide rely on Perforce Software Inc. to drive their business-critical initiatives. With its portfolio of scalable DevOps solutions, Perforce helps these organizations to overcome complex product development challenges by improving productivity, visibility, and security throughout the product life cycle.

In 1995, Perforce was founded to deliver version control software. Since then, the company has expanded its portfolio organically and through acquisition to include solutions for agile planning, application lifecycle management (ALM), API management, automated mobile and web testing, embeddable analytics, open source support, repository management, static code analysis, IP lifecycle management, and more.

Today, many of the product teams at Perforce have come to rely on MadCap Software to deliver localized modern Help and documentation to their users. MadCap Flare single-source, multi-channel authoring software is driving innovation in new and future releases of their content. Other key products include MadCap Central for cloud-based collaboration and analysis, MadCap Lingo for advanced computer-aided translation management, and MadCap Capture for screen capture and image editing.

“Perforce has acquired a lot of companies, and when it makes sense, those product teams have been adopting Flare to deliver web-based Help and PDFs,” says Amy Kearns, a technical writing manager at Perforce. “It’s been cool how we've been able to help those teams quickly migrate to Flare from a variety of different applications and formats.”

Delivering Intuitive Guides on the Web

Some of the Perforce solutions long supported by MadCap Flare-based documentation include ALM, Agile project management, and version control. The company produces between 25 to 30 guides for the Helix ALM line, which includes five products; 7 guides for its Hansoft Agile project management software; and 35 guides for the Helix Core, Helix4Git, and Helix TeamHub version control solutions. Collectively, the web-based guides help customers to install, use, administer, and integrate the products.

In the past, much of the documentation was published as PDFs. Today, the guides are primarily delivered as interactive, modern HTML5-based Help featuring a responsive design that adjusts to users’ screens; easy-to-use side navigation; and an intuitive search experience. For example, with the version control guides, Perforce offers search tips at the top of the search page, options for finding multiple search terms, and a different highlight color for each search term. The HTML5-based guides also let users narrow their searches by putting double quotes around terms, such as entering “work” to automatically remove any results for “workspace.”

“There are so many things we can do with the Flare native search that makes it easier for customers to find specifically what they are looking for,” notes Jeanne Wiegelmann-Alfandary, a technical documentation manager at Perforce.

In addition to letting customers search or visit the Help website, some product information, such as documentation for the ALM and Agile project management products, is also available as context-sensitive Help directly within the software.

“We rely heavily on the context-sensitive Help in Flare. It’s great the way a customer can be on the product screen and click a Help button to get the related Help topic,” Amy explains. “I’ve also used Flare to embed a term that we don’t use in our products into a topic, so if users search on the term, it will open the topic with the concepts they need.”

The ease of searching Perforce product guides and Help topics has led to increased use of documentation by customers, as well as the company’s internal teams.

“Our support team members are heavy users of our Flare-based Help, and they direct customers to it as a first resource whenever they can. That has really reduced support calls,” Amy notes. “It’s even to the point where developers will share a URL for a Help topic when people ask questions internally. Both our developers and our support team know our Flare-based Help is a resource they can trust.”

To create a seamless, intuitive experience, Perforce technical writers take advantage of skins and cascading style sheets (CSS) in MadCap Flare and then work with the company’s marketing team to incorporate the applicable branding. Additionally, documentation for the ALM and Agile project management products includes screenshots created using MadCap Capture.

“The style sheets, skins, and master pages in Flare were all very easy to learn, and using Capture, I can get the screenshots, edit them, add labels, and customize them in other ways,” Amy says.

Driving Efficiency and Content Consistency

In addition to improving the user experience, Perforce technical writers have taken advantage of MadCap Flare’s capabilities to simplify their work and streamline projects. Key among these is topic-based authoring, which facilitates content reuse and consistency.

“While I work on a release-to-release basis, I always push out Help in between, so I’m typically making updates every two weeks,” Amy observes. “What I love about Flare is that it’s so easy to publish new content quickly, and our content quality and consistency have improved because of content reuse.”

Perforce technical writers also make extensive use of conditional text. For example, the company’s Helix ALM product has a desktop-based client and a web client. The conceptual information is largely the same for the two clients, but the step-by-step, task-based information differs significantly. With MadCap Flare, the team can use the same topic but then use conditions to designate content that is either desktop client or web client only.

“With conditional text in Flare, I'm not maintaining two topics. I have everything in one place, and I can see where the differences and similarities are,” Amy notes. “We’ve been adding a lot of features to our web client, but I can just update existing topics for the desktop client with conditional text for the web client. It feels great to go to my manager and say, ‘We added these 12 features, but I was able to crank the content out quickly using our existing content’.”

Meanwhile, the version control documentation team relies on conditional text in MadCap Flare to adjust each table of contents (TOC) for its HTML5 and PDF outputs.

“We use the same table of contents for the PDF and HTML5 versions of our manuals,” Jeanne explains. “With Flare, we simply use conditional text to hide the additional topics that we don’t publish in the HTML output, like the cover page, TOC page, and glossary page. I can’t imagine having to manage all the TOCs without Flare.”

The Perforce team also makes wide use of snippets in MadCap Flare. For example, guides for three of the five ALM products might have the same paragraph. Using snippets, a technical writer can import the paragraph from a global project into the appropriate product guides.

“With the global project in Flare, I can maintain a snippet of information in one spot and use it across the product lines, which is nice,” Amy says.

Notably, global project linking in MadCap Flare provides an efficient way for Perforce to ensure consistency and compliance across outputs. As with many companies, Perforce uses third-party software to develop its products and has to publish the copyright information. Across the five ALM products, there is one topic called “third-party licenses,” where the third-party license information is maintained.

“Using global project linking in Flare to ensure that we include the right copyright information in our outputs is critical for compliance and has been a life saver for us,” Amy notes.

Analyzing Content and Users’ Experiences

Groups across Perforce are using different analytical capabilities to improve their content. For years, technical writers at Perforce have relied on the Analyzer functionality built into MadCap Flare, which checks for broken links, recommends opportunities to add snippets, and offers other reports and suggestions for improving their documentation.

“We run Analyzer before we publish our documentation, to find broken links because we discover things that we hadn't noticed,” Jeanne says. “It’s been very useful.”

More recently, some technical writers within Perforce have begun using MadCap Central. For example, the team has turned to the analytics functionality in MadCap Central to understand how its ALM and Agile project management guides are being used, answering such questions as: What are customers looking for that they are not finding? And, what topics are most used or most looked at?

“We were able to implement MadCap Central analytics quickly and get the data that we need,” Amy explains. “It has worked out well for us. We’re seeing that there's terminology or keywords our customers search for, which we may need to embed in the Help. It also shows us popular topics, as well as the operating systems and browsers that our customers are using, indicating that we should test on those more popular browsers.”

Facilitating Translation with MadCap Lingo and MadCap Central

Within Perforce, some teams need to localize content in Japanese. To facilitate translation, they are using MadCap Lingo computer-aided translation management software, which is tightly integrated with MadCap Flare.

The static code analysis group has an in-house Japanese translator who is also a technical writer and uses both MadCap Flare and MadCap Lingo to produce Japanese-language content. Meanwhile, the version control team relies on MadCap Lingo to package up each manual for an external translator.

“When we translate, we export our Flare content into Lingo and break it up by manual, so we have a different Lingo project per manual. Then we create bundles for the translator and send them out,” Jeanne notes. “Once we get the localized content from the translator, it will be identical to my Flare version, and it will work exactly the same way.”

Powering Automated Diagnostic Messages

Within the Perforce static code analysis group, MadCap Flare has gone beyond supporting the development of online Help and documentation to enabling automated diagnostic messages directly from the Helix QAC software. Helix QAC analyzes customers’ code, and then if code is incorrect or breaks syntax, it generates a message indicating the nature of the error. Originally, these diagnostic messages were generated using the LaTeX mark-up language, but it couldn’t be translated or converted to other formats.

Frustrated by the limited functionality of LaTeX, the static code analysis group replaced it with MadCap Flare, using snippets to automatically generate messages about different code errors. Collectively, the 26 Helix QAC products now rely on some 30,000 snippets embedded in the software to produce the messages. Facilitating the effort was the fact that both MadCap Flare and Helix QAC are based on standard XML.

“One of our products, alone, has about 3,000 of these diagnostic messages, which are part of the code and have to stay part of the code, but I wanted them in Flare,” Brian recalls. “So I got the developers to automatically push their XML into my Flare project, which then drops automatically into my reports. Everything is created as fully formed messages, which appear as lines of text, and they are all snippets. I don't have to do anything with them. And, we're doing that in Japanese, so it's all automatic down the line.”

Keeping Pace with Agile Development

Perforce technical writers in the static code analysis group need to manage 500,000-plus words of documentation. In the past, this content was typically six or more months behind the software releases. Now with MadCap Flare, the writers can keep pace with product versions as they are rolled out. The MadBuild functionality further streamlines efforts by fully automating all builds of the Flare output.

“Lately, I’ve been balancing my technical writing and project management roles, but in the past, I never could have produced more than half a million words of documentation in time for our product releases without Flare,” Brian says.

Another advantage of MadCap Flare is that it has brought search capabilities to both the documentation and the snippets that power automated messages within the software.

“With Flare, we now have half a million words and 30,000 snippets that can all be searched,” Brian notes. “Now, with this search functionality, I’ve figured out how to join searches together, which means we'll also have a combined search quite soon. Flare lets me be creative.”

Innovating with Help from MadCap Software Support

In addition to MadCap Software’s products, the company’s technical support team has also helped Perforce’s teams to drive innovation in their documentation and the Helix QAC product family.

“Years ago, I emailed both Adobe and MadCap Software with a question,” Brian recalled. “MadCap Software put two developers on the line who said, ‘Our team is currently working on this feature, but we can share what we’ve got so far.’ I still haven’t heard back from Adobe.”

Brian added, “I’m constantly pushing Flare past the boundaries of what it is designed to do, and the support team is always there to talk with me.”

Sometimes the MadCap Software team does not even wait to receive a call, notes Amy: “One time, I put a question out to our Cincinnati Flare user community on Slack. Someone from MadCap actually responded on Slack saying, ‘This sounds like a bug. Can you report that?’ It’s nice the way she reached out. MadCap does a great job of establishing relationships with customers and making sure people are happy and getting what they need.”

Looking to the Next Documentation Wave

Recently, groups within Perforce have completed proof-of-concept (POC) projects that utilize the new MadCap Flare developments in microcontent and code snippets. For the ALM and Agile project management documentation, Amy debuted a prototype of microcontent at a two-day Perforce Kickstart competition, which usually highlights developers—and won.

“The Flare-based microcontent prototype got a lot of great feedback from our support team,” Amy noted. “They were really excited about how the better targeting and search results will help customers. I can’t wait to roll out microcontent in our HTML5-based guides.”

Brian has also implemented prototype versions of documentation using microcontent and code snippets in MadCap Flare.

“I love the code snippet feature in Flare,” Brian says. “It’s simple; it’s wonderful, and I know I can use it in the diagnostic messages within our Helix QAC products.”

Amy adds, “It’s great the way Flare handles the heavy lifting. It makes my job a lot easier and lets me concentrate on the things that are important in the content.”