Thanks to a complimentary ticket from MadCap Software, I was able to attend the MadCap roadshow when it came to the Vancouver area. This event was held at the Hilton near Metrotown, in a pleasant meeting room. We were given free T-shirts, continental breakfast was served, and then we got down to business. Later in the afternoon, we were treated to an ice cream station.
Introduction and Presenter
The presenter Mike Hamilton is a former BlueSky (formerly the makers of RoboHelp) employee who began his career in the nuclear power industry. His complaints about the poor manuals pushed him into a role improving these manuals, and his new career was thrust upon him.
MadCap was born after a massive layoff of RoboHelp employees, which followed some previous acquisitions of RoboHelp by other companies. This laid-off group decided to form a new company. Ironically, MadCap has ended up in the same office building as the RoboHelp team once had.
Mike is an engaging and effective speaker. On the whole, the balance between marketing content and vendor-neutral information was fair.
See Mike’s MadCap Musings: http://madcapsoftware2.wordpress.com/
Topic-Based Authoring and Content Reuse
Topic-based authoring, even if it’s not DITA or DocBook style, is the key to successful content reuse. Topic-based authoring, combined with significant upfront planning, allows single-source publishing. In a successfully established documentation system, the user will not edit the deliverables directly, but will instead only edit the inputs to obtain the desired deliverables. Upfront planning includes determining exactly what formats, with what information, are required for the output. Mike also insists on the importance of a style guide and templates, even for lone writers. Determine what conditional text and variables must be used, in advance.
The unique “Snippets” feature in MadCap makes reuse somewhat easier, by providing a library of reusable content.
Although most users think of text when planning for content reuse, graphics and multimedia objects can also be reused, particularly with the various features that MadCap provides for conditionalizing components of graphics and multimedia.
See: http://www.madcapsoftware.com/solutions/multimedia/
MadCap Flare and Translation
Efficient content reuse and topic-based authoring facilitate efficient, cheaper translations. Translators can either work directly with Flare, or they can use the MadCap translation management product Lingo.
See: http://www.madcapsoftware.com/products/lingo/overview.aspx
Flare can also be used with other translation management tools, like TRADOS.
Multi-channel Publishing
A typical use case for technical writers is that you want to publish documentation for several different formats. Flare makes the process of setting up separate tables of contents and output instructions for each format simple. For example, the print format may not use the same format for web links as the online format does. Mobile documentation may be much sparser than the standard documentation, and so forth. Flare includes features that make the production of online, mobile, and print documentation easier than it would otherwise be. Flare 6 is said to provide significant functionality and usability improvements in this regard.
Team Authoring Techniques, Including Authors Other Than Tech Writers
You need to have a project storage system that allows collaboration and avoids writers overwriting each others’ work. Flare projects can be stored on a local machine, or on a network, or in a network source control system. Now, Flare templates can be stored on the network, even if the other content is stored on users’ local machines. Whatever method you use, backups are crucial, as hard drive failures are inevitable.
Getting subject matter experts to review Flare topics is difficult if you provide the SMEs with the straight XML, because it will look quite messy in most cases. You can, however, use MadCap X-Edit Review to facilitate the review of Flare topics. The user sees the correctly formatted files, and can annotate them as desired.
See: http://www.madcapsoftware.com/products/xedit/overview.aspx
For writers who do not have Flare, a common workaround is to have them use Microsoft Word, and then import to Flare. Keep in mind that subsequent Word edits mean the Flare files will be out of date.
Data Collection and Analytics
Mike discussed how you can determine whether your documentation is helpful to the customers, and whether the customers think that it meets their needs. If the documentation is on a web server, you can analyze the server logs. You can set up surveys, but if you do so, make sure to make them easy and pleasant for the user. You can encourage customer feedback with a feedback form, and allow for customers to select a page rating for each page. MadCap Flare facilitates all of these options. The MadCap Feedback Server is particularly useful if you need to do advanced and detailed evaluations of customer feedback.
See: http://www.madcapsoftware.com/products/feedback/overview.aspx
Using CSS (Cascading Style Sheets) to Control the Look of Your Output
For non-Flare users, this was likely the most useful part of the presentation, because the CSS tips and tricks are generally applicable. Although I have worked with CSS off and on for a number of years, I found Mike’s discussion to be a very useful explanation and summary, and I learned some features for the first time.
Particularly Useful Observation
Mike pointed out the need to keep all stakeholders in a project happy: the business owner, the manager, and the customer. A focus on perfect documentation, without regard for cost and time, may make the customer happy, but will lead to making other stakeholders quite unhappy.
Drawbacks of MadCap Flare
Afterwards, I explained to Mike Hamilton some of the specific concerns that might stop my current company from adopting MadCap Flare as an authoring tool. Mike listened, and without committing to any future improvements, suggested that some items in the pipeline might make Flare a more appealing option, at least in some respects. My main concerns were Flare’s lack of support for editing directly in DITA, although it is successfully used as a tool for generating output from DITA-composed documentation, and Flare’s lack of mathematical equation support. For general software documentation use, however, I was quite impressed by Flare’s capabilities.
See for Yourself
My summary of the presentation inevitably misses some important points and cool features. The best way to see what MadCap Flare has to offer is to obtain a trial CD, or download the trial version from the website.
The following links lead you to trial software, free webinars, and online demos:
