Enhancing Online Help with MadPak Suite Components

Patrick Calnan, Documentation Team Lead for N‐able Technologies has been using components of the MadPak Suite for a while, and presented at WritersUA on how MadPak Suite can enhance online help in a quick 30-minute session. Although he’s not a MadCap employee, Calnen packed a lot of useful information into a short session, effectively touching on several components of the MadPak Suite with insight on how his company has implemented them: Feedback, Analyzer, Contributor, Mimic and Capture.

MadPak Feedback has two options—Server (Web server application) and Explorer (local client)—to obtain usage statistics, and for commenting on or rating help topics. Calnan spoke about using MadPak Flare to generate online help. The team an N-able Technologies uploads Flare help to the same server where Feedback Server is loaded, and uses Feedback Explorer to gather statistics on the assistance, including tables for the number of people looking at the different topics and displayed comments.  Users must have Feedback Explorer (a free distributable application) to locally pull reports from Feedback Server, but anyone can access the statistics that way, not just the Server administrator. The statistics include both users’ topic views in the online help and the context, and the help pages users go to from within the application. It also rates search terms users input and records any null searches, terms users put in that receive no search results. In 2011, Feedback 4.0 added the new feature that records the users’ browser types, which can be very helpful information, especially for web-based help projects.

Calnan noted the pros and cons MadPak Feedback, such as the relatively few ratings or comments n received (other than those requiring a call to their help desk). His team has been able to use Feedback to discern what content users read or find important in the online help, which they use to revise content with new emphasis points. They also use search statistics refine search terminology to map to what their users actually input. He mentioned two caveats:  1) the heavy administrative work necessary to implement the software; and 2) the price increase if MadCap handles setup and configuration.

MadCap Analyzer offers more extensive trouble-shooting components than those in Flare and can troubleshoot your entire Flare project without regard to output. Analyzer also delivers recommendations on repairing problems too, suggesting improvements for style sheets and content, identifying broken links, etc. Calnan pointed out one of his favorite features—Flare does not need to be open in order to troubleshoot a Flare project. Instead, Analyzer opens one segment for review and editing. The software produces a log of issues with links directly the part of the online help project containing the issue. Analyzer integrates with Flare and provides good source control functionality identical to Flare. However source control must be configured in Flare. While he encouraged attendees to develop their own processes, Calnan recommended a three-part workflow his company found most expedient:

  1. Use Project Analysis in Flare before generating targets
  2. After generating targets, save the Log, especially if there are errors;
  3. Use Analyzer only at project milestones (due to lengthy scanning time).

Calnan also noted that, in addition to the lengthy runtime, Analyzer logs a number of non-critical recommendations that must be weeded through.

MadCap Contributor replaced X-Edit in the MadPak suite, and allows for multiple contributors to a Flare project without having Flare itself. Contributor allows editors of content to avoid the learning curve of Flare. Calnan agrees that building content in Contributor is also better than Word or other word processing software, because its XHTML transfers to Flare and speaks to Flare, without requiring a lot of work in Flare to correct formatting. Calnan spoke to the short learning curve on Contributor, pointing out that it functions like any other word processor, only requiring a minimal understanding of styles. A free version of Contributor runs in review mode and allows annotating but not composing. Besides the relatively easy learning curve for reviewers, the only other negative Calnan pointed out is the non-cyclical review process—file formats differ from Contributor (.MCCO) to Flare and Flare (.FLTREV) to Contributor, and thus only allow for viewing one iteration of edits at a time.

MadCap Mimic  produces simulations and animated tutorials, which can be embedded in online help. The software also produces standalone outputs (Mimic Movie or Adobe AIR for desktop, MS Silverlight or Adobe Flash for Web, MS XPS or Adobe PDF for print), and shares  files between Flare and Mimic. While Calnan’s team chose not to use it (they don’t embed their tutorials into help), he suggested that it is very useful for those purposes because of the integration with Flare. He also pointed out that the Mimic Movie desktop viewer is a free download from MadCap. On one hand, technical writers can launch Mimic from within Flare, insert tutorials/movies directly into Flare topics, and take advantage of Flare variables. Calnan also found that the learning curve is not too steep and that the MMF output is XML based. On the other hand, MMF is a proprietary format, and Calnan believes the software is not as powerful as other simulation tools.

Like the more well-known Snagit, MadPak Capture is a simple screen capture tool that provides multiple capture modes (active window, full screen, region, or shape area) and uses keyboard shortcuts. Capture, however integrates well in Flare, allowing captures from the Flare UI and launching from within Flare. It also allows users to edit the captured image, such as adding shapes and text boxes. It supports multiple outputs: BMP, HDP, JPG, JPEG, GIF, PNG, TIF, TIFF, WDP, and XPS. An attendee also pointed out that UI changes/annotations are saved in layers on top of the capture, so technical writers can easily recapture images without losing supplemental work. Calnan added that layering keeps the added text/annotations in XML, which simplifies translation processing for localizing documentation and online help.

Calnan concluded by pointing out that MadPak Lingo, the component that provides translation management, is worthy of its own session.  He encouraged attendees to purchase the Suite to make it easier to get started rather than the separate components as his company did.

TechWhirl’s coverage of WritersUA 2012 is sponsored by Madcap Software. Find out more and download a trial copy of Flare 8.

Subscribe to TechWhirl via Email