By Ed Marshall | Senior Member
FLARE 6, released early this year, is the latest version of the state-of-the-art help authoring tool produced by MadCap Software. The major new features of Flare 6 include:
- A new WebHelp Mobile output format for mobile devices.
- Capability to batch generate and publish your output formats.
- Ability to assign writers/status to topics (called file tagging). You can generate custom reports showing the workload for each writer on the team or generate a list of topics with a selected status.
- Enhancements to creating/modifying index entries.
- A new GUI option to view links to/from topics, called Link Viewer.
- Other usability/workflow enhancements.
- Capability to import multiple HTML files into a Flare project (previously you had to import them one at a time).
- Ability to import RoboHelp 8 projects into a Flare project.
- Enhancements to Flare’s integration with commonly used source control software.
MadCap provides a very useful “What’s New in This Version” topic in the help for all of their products, including a complete list and a very useful discussion of the new features of that release. This article discusses several of these new features and provides examples of how and why you might use them.
Producing WebHelp for Mobile Devices
The new WebHelp Mobile output format (output formats are called targets in Flare) enables you to deploy a set of web pages (in XHTML format) to mobile devices. The target is designed to work on very small screens. From the home page, you can access the typical navigation panes such as TOC, Index, Glossary, Search, Favorites, and Browse Sequences. A key advantage of this output is that it is platform independent. This means that your output will work on a variety of mobile devices, including iPhone, Windows Mobile, and Blackberry. This helps you avoid the problem of having the output format tied to one platform while other platforms are not supported. This is a huge advantage to help developers. You don’t need to worry about what platform your users are using. Figure 1 shows a default home page for the WebHelp Mobile target (output).
Design Considerations
This target is designed to automatically flow and resize the line length to accommodate the viewing area of the mobile device. You don’t have to do any special formatting or coding for this to happen.
You might have to modify headings, screenshots, graphics, or tables if they are wide. Those constructs will still appear in your output, but the user might have to scroll so much that the elements become essentially unusable. One approach is to conditionalize large constructs such as graphics or tables for the limited screen size of mobile devices. That is, you would have a full-sized version of these elements for your help outputs for PCs and a much smaller, possibly redesigned version that you conditionalize for the WebHelp Mobile target. Additionally, if the mobile device is turned from a vertical orientation to a horizontal orientation, the text will automatically reflow to better fit the changed dimensions of the viewing area.
The preview feature of the WebHelp Mobile target output is very helpful to writers. It allows you to test and debug your help projects for this new output even if you don’t have a mobile device. You can navigate the preview just as you would on an actual mobile device, so that you can see what elements need to be customized for mobility.
There are a few limitations to this target, mainly due to limitations in mobile browsers:
- Audio and movies are supported if the mobile browser supports them.
- Search features such as including/excluding topics in search, stop words, and synonyms are only supported in the newer mobile browsers.
Generating and Publishing Multiple Output Formats
With Flare 6, you create a batch or “master” target that consists of several output formats or targets. This is useful if you have multiple output formats, such as WebHelp and PDF, that you want to build on a regular basis. Instead of an automated build for each of those targets, you can now set up a master build that will run all of your output formats. You can customize the build and select options for each target within the master build, which gives you tremendous flexibility. As with the individual builds, you can always make changes to the builds within the master build.
The steps involved:
- Create a batch target, such as “MyBatchJob.” Figure 2 shows the default MyBatchTarget window.
Figure 2. The default MyBatchTarget window - Optionally, set a time when the batch job will start. For example, you might want the job to run every night at 2:00 am (when you won’t be using your computer) to minimize disruption and the elapsed time for the specified targets to build. Flare not only builds all your targets but also copies the output files to the specified publish directories.
Figure 3 shows the Schedule window used to create a schedule for your batch job. Once you set up this schedule, you don’t have to leave Flare open to have the scheduler run. Also, Flare automatically generates and saves a report for the batch job so you can easily troubleshoot any problems the next morning.
Figure 3. The Schedule window - Save your BatchTarget. It will appear in the list of Targets in the Project Organizer.
- Optionally, you can always kick off a manual build of your batch job. Just click your BatchTarget in the list of Targets in the Project Organizer. In the BatchTarget window, click one of the tabs on the top to Build and Publish, Build Only, or Publish Only.
You can easily make changes to when or how often a batch job runs, and what targets to build. This feature can be very helpful if you have multiple targets, such as WebHelp, HTML Help, and PDF, and you want to always know that your builds are successful. This is similar to the build systems that developers use to reflect the latest changes to software and a regularly scheduled verification that the build compiles successfully.
Assigning Topics to Authors Using File Tagging
With this feature, you can add as many authors as you need for a help project and assign them to topics. Once you’ve added authors and assigned topics to them, you can then easily generate a customized report showing each writer’s workload and other useful information.
To add authors:
- In the Project Organizer, select a target.
- Right-click the selected target and select Properties.
- In the Properties dialog (see Figure 4), select File Tags on the left. The default is to display the Author tags with two predefined authors: Author1 and Author2.
Figure 4. The Properties dialog - To add or remove writers from the target, ensure Author is selected in the Tag Type dropdown.
- Click Edit Set to display the FileTagSet Editor. You can easily add new tag names, delete the defaults, etc.
- To add a new author, click the New Item icon (the second icon to the right of FileTagSet Editor in the toolbar above the Tag Name/Comment headings). Flare inserts the default text of NewTag in a new row at the end of the current list. Select the NewTag text and enter the author name to be added (see Figure 5).
Figure 5. The FileTagSet Editor - When you are finished, click the OK button to apply your changes.
Assigning Status to Topics Using File Tagging
With this feature, you can add as many Status types as you need for a help project and assign them to topics. Once you’ve created your status types, you can easily generate a customized report showing the status of projects and other useful information.
To create custom status types:
- In the Project Organizer, select a target.
- Right-click the selected target and select Properties.
- In the Properties dialog, select File Tags on the left. To see the predefined Status tags, click the Tag Type dropdown and select Status. Figure 6 shows the default Status tags of Complete, In Progress, Ready for Review, and Ready for Translation:
Figure 6. The default Status tags - To add or remove Status types from the target, ensure Status is selected in the Tag Type dropdown.
- Click Edit Set to display the FileTagSet Editor. You can easily add new tag names, delete the defaults, etc.
- To add a new Status type, click the New Item icon (the second icon to the right of FileTagSet Editor in the toolbar above the Tag Name/Comment headings). Flare inserts the default text of NewTag in a new row (see Figure 7). Select the NewTag text and enter the new Status type.
Figure 7. The FileTagSet Editor dialog - When you are finished, click the OK button to apply your changes.
Generating Status Reports for a Flare Project
You can easily generate a Status Report for your Flare project using the Reports option found in the Project Organizer.
Flare 6 provides a handy and easy-to-use Review toolbar. You can also generate a view of all the files in your project with several columns displaying Name, Path, Size, Date Modified, Status, Author, and many others. Consistent with MadCap’s philosophy of making your workflow easier, you can select the columns you want to display in the File List. For the purposes of viewing statuses, you would select Name, Author, and Status as your columns.
For example, if you want to send all the topics that have a status of Ready for Review, you could sort the Status column and then select all the topics that are Ready for Review. Flare provides a Send Topics for Review Wizard. The wizard provides an email template, partially filled in with an appropriate subject and default message, requesting the recipient(s) review the attached topics. You specify the recipient’s email address and click Send. This is so much easier than how I tracked topics in a help system years ago and hand-collated the lists of topics to review.
Enhancements to Creating/Manipulating Index Entries
In Flare 6, it is easy to add index entries with the new Index window (see Figure 8). You add index entries/subentries in the top pane. The bottom pane shows you all the index entries in your project. The topics containing an index entry will be listed under the appropriate index entry in the bottom pane. One benefit of the Index window is that you can easily drag and drop topics onto index entries, which results in those entries being added to those topics.
One easy way to use this new feature is to position the Index window alongside your list of topics in your project (in the Content Explorer). During a dedicated indexing session, you could just drag and drop topics from the Content Explorer to index entries you’ve created. This approach results in a comprehensive index with not just syntactical entries (a list of function names) but actual tasks (such as creating or publishing messages).
Viewing Links to/from Topics
The Link Viewer feature gives you a more complete view of links to and from a selected topic. You can open any of the files listed in the Linked From or Linked To columns to open those files for editing. You can also view which targets are linked to a file so you know what outputs will change if you alter the content of that file.
A nice enhancement to the link checking capability is that you can lock the current view. This is useful if you need to browse several files to determine potential changes to them. By default, the Link Viewer will automatically refresh to show the Links From/Links To the new selected topic. But if you lock the Link Viewer, the display is frozen to the selected topic, so you can backtrack all the links from/to that topic while keeping a static view of your starting topic.
As you might expect, this feature displays any broken links with the customary red X. This feature is a big improvement over the Show Dependencies feature in earlier versions of Flare.
Other Usability Enhancements
The Skins Editors have been enhanced to only show settings that apply to that skin type. The Skins Editor also includes options for the new WebHelp Mobile output.
The Target Editor has been enhanced to only show settings relevant to that target type. For example, PDF options now only appear for the PDF Output Target. Each target listed in the Targets list has an appropriate and easily recognizable icon associated with that target so you don’t have to open the Target Editor to see the type for that target name.
It is much easier to create a template for a file, because now you can save an existing file or project as a template. It is also easier to manage your template files, such as adding them, creating template folders, and editing templates.
Flare provides a set of the most commonly used default options for customizing WebHelp toolbars and the Topic toolbar. You can easily exclude any of the default options. And Flare added a new button in the Editor that allows you to add a separator lines between a subgroup of related options.
Importing Multiple HTML Files at Once
You can now import multiple HTML files into your Flare project. You might need this if you are adding content from SMEs or other sources. Previously, you could only import HTML files one at a time.
Importing RoboHelp 8 Projects
Flare can import Adobe RoboHelp 8 projects into the appropriate Flare constructs.
Enhancements to Flare’s Integration with Source Code Control Tools
Flare 6 makes several enhancements to its integration with source code control software, such as Microsoft Visual SourceSafe (versions 2005 and the venerable 6.0) and Microsoft Team Foundation Server. Flare provides the following enhancements:
Displays two new icons to indicate the following status of files:
- New files added to your project that haven’t been added to your source code control system.
- Files in your project that are not current with the latest version in your source code control system. This alerts you when you need to update your local version of those files.
- Ability to merge changes between two versions of a file within Flare. When you check in a changed file, Flare confirms whether any other changes were made to that file, such as by another writer. If there are two versions, Flare displays a dialog where you can merge the changes or discard one set of changes. If there are no conflicting changes between the two files, Flare offers the option to Auto Merge All.
Flare now provides icons that show the status of your files, such as files that are checked out by other users or files that are out of date (your local copy is older than the copy in the source code control tool).
The Check-In and Undo Check-Out dialogs now allow you to display only the files that have changed. This can be helpful to show you a subset of your project with only the changed files displayed, instead of all the files in your project, so that you can determine which files actually need to be checked in.
Summary
Flare 6 is a well-done major release of the state-of-the-art help authoring tool from MadCap Software. WebHelp Mobile is an important new feature that technical writers should investigate. With the proliferation of mobile devices and social media, the area of user assistance for mobile devices is extremely popular, and recent evidence supports this conclusion. At the 2010 WritersUA conference, there were two full-length presentations about writing for mobile devices and a demo by Neil Perlin at the MadCap booth. And I’ve received at least two inquiries in the past month for contract jobs working on mobile devices.
I’m especially impressed with the usability improvements in this version of Flare. It’s not often that makers of a mature product will revisit their workflows to see if they are really efficient. MadCap deserves praise for these productivity improvements to Flare. A full-featured trial version of Flare 6 is available from www.madcapsoftware.com/downloads/?p=PFL.
Along with Flare, MadCap also makes several other tools that are completely integrated with Flare, such as Capture, Analyzer, and Mimic. See www.madcapsoftware.com for a complete list.
Thanks to Anthony Olivier (MadCap CEO) and Mike Hamilton (VP of Product Development) for providing me with a copy of Flare 6 to review and for information on the new features, to Sharon Burton (Flare Consultant) for an excellent webinar highlighting the changes in Flare 6, to Neil Perlin (Certified Flare Trainer) for an excellent demo of the new WebHelp Mobile output, and to Cheryl Landes for a thorough edit of this article.
Ed Marshall (ed.marshall@verizon.net) is an independent technical writing consultant and sole proprietor of Marshall Documentation Consulting (www.marshalldocumentationservices.com), with more than 22 years of experience. He specializes in APIs/SDKs (application programming interfaces/software development kits), web services products, and other types of documentation. Ed has developed expertise in using tools to “let the computer do the work,” such as advanced tools for editing files, comparing files, and searching and replacing text in files. A popular speaker at a variety of local and nationwide professional development conferences, his previous appearances include events sponsored by STC, WritersUA, and DocTrain.
