Developer Product Briefs
Develop Help Content Like a Professional
MadCap Flare 4.1 offers must-have features for technical writers.
MadCap Flare 4.1 is a professional development environment for creating documentation for a wide range of formats based on a single-source (XML). As a programming writer, I was struck by how Flare offers so many must-have features of Visual Studio to technical writers.
Information developers have much in common with software developers. They want to work in a familiar, integrated environment that organizes files, flags errors, assists with testing and reporting, controls the build process, and generally makes them more efficient. Flare does all this and more. For example, it takes a cue from software development by allowing projects to link to common content. As with pre-built software components, you can store and update shared pages -- for example, legal disclaimers -- in one place. All of the projects and documentation suites can incorporate the latest version into the build automatically.
IntelliSense, an essential feature for writing code, is now available in documentation projects. As you write instructions, the IDE suggests phrases that appear in the project's topics. Likewise, you can drag snippets and drop them directly into a topic.
[Click on image for larger view.]
|Reduce keystrokes and writer's cramp
You can store frequently used resources as snippets in MadCap Flare 4.1. Just drag-and-drop the content into the editor. For larger files, you can link to complete boilerplate topics from a central location.
To accommodate Windows Presentation Foundation (WPF) and Silverlight software projects, Flare now supports an array of vector graphic types, including the XAML format. A nice touch is the ability to convert those images automatically to Web-safe formats such as .GIF or .JPG for browser-hosted output. Speaking of formats, Madcap creates .PDF and .XPS files directly, without requiring Microsoft Word, Adobe FrameMaker, or Adobe Acrobat as intermediaries. Unfortunately, MadCap still doesn't generate files that integrate with Visual Studio's help collections (MS Help 2). Another valuable output would be XAML markup for Silverlight apps.
Source control is essential for programmers and writers alike. When you create a Flare project, there's a checkbox to bind to a source control provider, including Visual SourceSafe, Team Foundation Server, and a generic plug-in. The Bind Project option recognized and connected to my SourceGear Vault provider -- a real bonus. That said, the IDE crashed when I tried to cancel out of a Vault connection using the Advanced option.
You'll appreciate the small conditional-text touches like automatically adjusting cross-references for the medium. For example, in a PDF you might generate "as shown on p. 32" where the HTML version, which doesn't use page numbers, would substitute a hyperlink.
MadCap's user assistance is polished and plentiful. The Getting Started Wizard, sample projects, videos, dynamic help, and help topics get you up to speed and over the hurdles.
On the downside, Flare sets off your firewall alarm as it accesses the network to validate your license key usage, and the software stops working until you -- or the IT department -- unblock its stealth access. With product announcements that start with "Dear Propeller Heads!" the folks at MadCap seem friendly, fun, and upfront. That's why a high-handed licensing approach is disappointing and out of character. VSM
At A Glance
MadCap Flare 4.1
Quick Facts: Integrated development environment for authoring user manuals, online help, and Web pages. Generates multiple output formats from a
single XML source.
Pros: File linking and conditional text; XML editor; IntelliSense support; drag-and-drop snippets; source-control friendly; command-line mode; built-in .PDF and .XPS generators; valuable user assistance.
Cons: Doesn't generate integrated help for Visual Studio help collections; sets off firewall alarm to validate license key.
About the Author
Ken Cox is a Canadian .NET programming writer and the author of "ASP.NET 3.5 for Dummies" (Wiley).