My Favorite New Features in MadCap Flare 9

The recently released Flare 9 continues MadCap’s practice of adding both in-the-weeds mechanical features and big picture strategic features (sometimes surprising ones, like QR codes in Flare 7). Several full reviews have already appeared, like this one by Ed Marshall – “MadCap Flare 9 – ‘Something for everyone’” at http://www.madcapsoftware.com/articles/CommunicatorArticle2013EM.aspx.  
In this post, I’ll look at some of my favorite new features. (For a full feature list, see MadCap’s web site - http://www.madcapsoftware.com/products/flare/overview.aspx - or the “What’s New in This Version” topic in the help if you already have 9.)

Mechanical Features

Synchronization of text highlighting between XML editor and code view

In prior versions of Flare, you might see an issue in a topic that you wanted to fix in code. The problem was that there was no way to find that issue in the code except by eye (“find the first bullet after the second image”) or using the Search feature. Both methods worked but weren’t very convenient.

Flare 9 appears to have solved this problem. Now, you can open the XML editor and code view windows, highlight the desired text in the XML editor, and see the corresponding text highlighted in code view, as shown below.

Clicking a block bar in the text editor selects and highlights that text in both editors. This certainly beats searching for the second bullet code by eye or searching for the words “If you choose…”

Print output enhancements

In my experience, most clients’ print outputs are pretty simple. However, an avalanche of new options let you take your print output far beyond simple, such as:

·         Support for crop marks and registration marks in PDF outputs to help your printer determine where to cut the paper and to ensure accurate registration in color printing.

·         Numerous mechanical enhancements for page layout work and new page layouts for starting a first page on the left or right page.

·         Support for CMYK colors in addition to the standard RGB.

·         More table handling options.

Flare should now be able to handle all but the most esoteric print needs. (For a clue as to the size of the print feature set, note that the downloadable PDF Print-Based Output Guide is almost 600 pages long!)

Advanced Expressions in Condition Tags

Flare lets you apply conditions to almost any feature, like creating conditionalized snippets that contain conditionalized variables. You can even apply conditions to conditions, though I’ve never seen anyone do this in a real project.  (If you have done this, please let me know why and how it worked out.)

For all its power, the condition tag feature has a simple basis – include/exclude. If you recall high school algebra, that’s a NOT statement, with an OR statement if you applied multiple tags – e.g. the statement “not ( Primary.HOLD or Primary.Print )” tells Flare to exclude (“not”) any object to which you applied the tags HOLD or Print from the Primary tag set. It’s easy to understand, although it’s easy to get the wrong results if you apply different tags to text, text paragraphs, topics, foldersful of topics, and so on.

Flare 9 boosts the power of the condition tags feature (and the risk of confusion unless you plan your conditions carefully). The reason is more powerful logic controlled through a more powerful option in the dialog box. The first screen below shows the familiar, basic, mouse-driven condition tag feature.

 

Here’s the same dialog box but in Advanced mode.

Here, you can use AND, OR, NOT, and () statements to create more powerful but more complex build expressions – e.g. formulas. However, this also adds some new things to watch out for.

·         There are no clickable selection functions other than that Copy From Basic button; you have to type the formula, with the risk of typos. So you have to type carefully and check your entry.

·          You can switch between Basic and Advanced modes but the two modes work slightly differently.

·          It’s easy to get confused over the different logical expressions. In my Flare classes, I always run a little exercise that asks people to calculate the result of an AND expression versus an OR. People often get it wrong the first time because the logic of conditionality differs from everyday logic.

·         It’s easy to create a complex and powerful build expression that you understand; what happens when you leave? If you don’t document your build expressions, and many people don’t because project documentation is usually something we’ll get to when we have time, your replacement may have a lot of trouble understanding what you did.

Basically, the advanced conditional build tags feature should let you create expressions to cover almost any need but it has to be used with care.

Large Strategic Features

Each of the features in this section is worthy of its own post. Here, I’ll sum up the features and suggest what impact they may have and cover them in more detail in later posts as time permits.

Office 365 Support (Word Import/Output Without Installation of Word)

For years, tech comm is typically done on a local PC. Flare and its projects, Word and its documents, and others – all sit on your C drive. That’s been changing with the spread of server-side version control and Flare’s native support for working on projects on network drives. Yet sometimes you don’t realize that a change is occurring until you reach a tipping point, in my case my discovery that I could put the graphics for a Flare project in the cloud and cut the size of the distributable output by 75%.

In my opinion, support for Office 365 may be that tipping point. Flare 9 users can work in the cloud but remain in the familiar Flare interface rather than having to bolt separate tools and processes together. The support is still in its early stage and the help notes some limits to that support, but this is the first step that I expect to see extended in later versions of Flare, just as Flare 8 introduced HTML5 support and Flare 9 is now extending it. (See below.) If you use Office 365 or are thinking about working in the cloud in general, read about this feature.

HTML5 Enhancements

Traditional WebHelp browser-based output has existed since 1998 and still works fine in most cases, but it does have some drawbacks that are becoming increasingly obvious in this web-based era. To address these drawbacks, MadCap added support for HTML5 output in Flare 8. (For an overview of HTML5, see “About HTML5 (WebHelp 2.0) Output” in the help.) Flare 9 offers a number of incremental additions to the HTML5 output to make it easier and more flexible to use. These include:

·         A search field on the index and glossary tabs. As users type more and more letters, Flare narrows down the list of possible hits.

·         Highlighting of search hits.

·         Box shadow effects for buttons on the toolbar, a simple aesthetic feature.

In my opinion, it will be awhile before HTML5 is as popular as WebHelp. This is because one of HTML5’s major strategic benefits, better searchability by web crawlers for better results in a Google search, isn’t that vital if your online material is behind a firewall and available only to subscribers. But HTML5 has other benefits that may be enough to tip you toward it. You can try HTML5 almost effortlessly by simply outputting an existing projects to HTML5 and comparing the result to your usual WebHelp or CHM.

eBooks and ePub3

In my experience, companies are increasingly looking at offering their material in mobile form and Flare has steadily expanded its mobile features since WebHelp Mobile in Flare 6 and ePub in 8. Flare 9 adds more ePub support, including new features, supporting the new ePub3, simplifying the esoteric process of validating ePub output, and adding mobi output for the Kindle.

ePub and mobi don’t support all the features that Flare offers, so you can’t just click a few buttons and get a result with a completely satisfactory design. But the mechanics of conversion to mobile are almost that simple. If you’ve been thinking about moving into mobile, Flare is getting closer to letting you do that for all mobile formats except “true” native apps and without having to buy and learn new software.

Pulse

Several versions ago, MadCap introduced the Feedback package that let you to create a virtual, Web 2.0 style community of users who could comment about topics in your Flare output, respond to other users’ comments, rate topics for their usefulness, and so on. This “community” existed independently, though you could moderate it (for obvious reasons). Feedback is still supported, but MadCap has now released MadCap Pulse as a new and more powerful version that lets you add a more powerful social layer to your output.

As an analogy, think of Pulse as something like a Flare-centric LinkedIn. It supports commenting, email feeds, communities, questions (like a survey feature), and several that I find to have the most potential - interaction with external systems  like social media sites and helping Flare authors determine what search synonyms, not index synonyms, are required to make searching more useful. Pulse also lets users add to the documentation set by attaching images, movies, additional links and other files, without affecting the documentation set itself. You can also create controlled Communities or Groups in which to set up discussions around specific topics and invite or restrict users to particular Communities or Private Groups.  For more information and a video on Pulse, see http://www.madcapsoftware.com/products/pulse/

Summary

Simply put, Flare is an excellent tool that continues to get better.

About the Author

Neil has 34 years experience in technical communication, with 28 in training, consulting, and development for various online formats and tools including WinHelp, HTML Help, CE Help, JavaHelp, WebHelp, RoboHelp, ForeHelp, Flare, and many now known only in legend.  Neil is a columnist and frequent speaker for various professional groups and the creator and manager of the Beyond the Bleeding Edge stem at the STC’s annual summit.

Neil is Madcap certified for Flare and Mimic, ViziApps certified for the ViziApps mobile app development platform, and certified in other help authoring tools.  He provides training, consulting, and development for online help and documentation, Flare, Mimic, other help authoring tools, mobile apps, XML, single-sourcing, topic-based and structured authoring, and content strategy through Hyper/Word Services.  He can be reached at nperlin@concentric.net, www.hyperword.com.

 

An Overview Look at MadCap Mimic 7

Mimic is a visual help or software simulation authoring tool from MadCap Software (www.madcapsoftware.com), maker of Flare. Mimic is available alone or as part of the MadPak suite, which includes Flare, Contributor, Analyzer, Capture, and Lingo. In this post, I’ll discuss what visual help/software simulation authoring tools in general and Mimic in particular do overall, then look at some specifics in Mimic and changes in v.7.

Visual help/software simulation authoring tools let you create visual training by recording tasks that you perform on the PC and saving them as “movies” that viewers can play.

For example, let’s say you have to train new users on how to add a client to a billing system. You can just write a textual description illustrated with screen shots; this is essentially what Flare does – create text-based help. But with Mimic, you can actually perform the steps for adding a client to the billing system and record each step on each screen. The resulting “movie” is essentially a slide chain or filmstrip that you can give to the viewers as is, or make more useful by adding explanatory text captions or voice narration on some slides, highlighting areas of screens that you want to emphasize, and more. The result is like having a guide who can “walk you through” each step in the task.

Creating these movies seems complex at first because of the need to plan the flow and sort through the many recording, editing, and output options, but the work can actually be surprisingly simple, quick, and flexible. You can create movies in days, hours, even minutes depending on your needs, and the resulting movies can be presented to users in various ways, such as:

·         As individual standalone movies presented on a training portal web page.

·         Integrated into topics in an online help system created using Flare.

·         Distributed via YouTube, making YouTube a free distribution mechanism.

And Mimic is inexpensive, $299 for new or starting from $149 for an upgrade. It’s an inexpensive way to add a visual dimension to online help, training, reference, or marketing materials.

Now for a closer look at Mimic 7.

There are six ways to create a new movie, as shown in the New dialog box below.

The simplest option is the Record Movie option. To use it, set up the software to record, set some Mimic recording options, and start recording. Mimic will record everything you do. (Including mis-clicks, so plan before you start recording to avoid having to edit the slides for errors or discard a movie and reshoot it correctly.)

Once you’ve recorded the slides, you can edit them. Much of that work is on a slide-by-slide basis using the interface shown below.

 

On the left is a palette of re-usable graphic objects that you can create. On the right is a list of frames in the movie, one way to navigate from frame to frame. The center of the screen is showing slide/frame 18. At the top of the slide is an initial text caption box “Click…” that Mimic added automatically during the recording. You can edit the text in this caption box as needed or just delete it. The red line below the text caption shows the path of the mouse pointer during recording. Viewers won’t see that line; they’ll see the actual mouse pointer move along that path.

In addition to the text caption boxes, you can add highlight boxes in various shapes, audio clips of sound effects or voiceover narration, simulated fields in which viewers can make simulated entries, animation that moves graphics along a trajectory on a slide, and more. Mimic movies can also use conditions and targets, as in Flare, and can be integrated into a Flare project programmatically so that the projects can share conditions, for example, and update automatically.

After recording and editing the slides, you have to generate the final output for distribution to viewers. Mimic 7 supports industry-standard outputs like Adobe Flash, plus Adobe AIR, Microsoft Silverlight, PDF, MadCap’s proprietary Movie Player output, and, new in Mimic 7, HTML5. Each of these outputs has its own options and it’s easy to create a movie, try one output, then switch options or output to multiple options as your needs change.

Should you buy Mimic or, if you have an earlier version, should you upgrade to 7?

Do you want to quickly create visual training movies or software simulations for use in online help, informal training, or web-side marketing or demos? Integrate the movies with online help projects in Flare? Then Mimic is an excellent choice – inexpensive, quick to learn and use, and tightly integrated with Flare.

If you already have an earlier version of Mimic, should you upgrade? The most obvious change in 7 is the interface’s shift from a toolbar to the ribbon. It’s a more up-to-date look and aligns Mimic with Flare 8. It also makes features like annotation object options easier to use. There are also added conveniences, like the ability to pick an output type to view or generate directly from the development pane. The video playback skin has been redesigned to be easier to use, and the redesigned timeline interface makes it easy for authors to navigate to any point in the movie. And, because Mimic comes from the same design base as Flare, it shares many concepts and features in common with Flare and other components of the MadPak suite, such as conditional build tags, variables, and targets. In other words, if you’re familiar with Flare, you’re already inherently familiar with some of Mimic’s most useful features.

However, I consider HTML5 output to be the main reason to upgrade. HTML5 is important if you plan to create movies to run on iOS devices like the iPhone, or be bundled into Flare projects output to Flare’s Windows Mobile output to run on iOS, or run on YouTube. You may not be planning to do any of these in the near future, but check with your management before writing off HTML5 and Mimic 7. Mobile is slowly but steadily pervading the world of tech comm, training, and marketing, and Mimic 7 supports it now, integrated into a familiar interface.

Neil Perlin is a MadCap-certified consultant and trainer for Flare and Mimic. Neil is an independent consultant based outside Boston, MA, operating as Hyper/Word Services (www.hyperword.com, nperlin@nperlin.cnc.net). He is the author of “Essentials of MadCap Mimic 6” (and the forthcoming “Essentials of MadCap Mimic 7”) and “Advanced and Unfamiliar Features in MadCap Flare”, both available at Amazon.

The Future of the Online Help Interface?

Thanks to Trevor W. for raising an interesting question after I presented a Dec. 11 webinar for #MadCap on the design challenges in converting traditional online help to mobile format…

The question:

With newer, touch-screen optimized operating systems like Windows 8 (and Apple’s Mountain Lion to some extent), and the merging of form factors--laptops and tablets (like MS Surface) --do you see a move away from more traditional online help layouts and towards a mobile-style layout for all platforms, including desktops? By mobile-style, I mean something that looks like your *** app with icons, rather than a stock mobile output…

My initial answer:

The short and honest answer is that I don't know.

The more useful answer is that our interface designs are evolving based on a number of factors including user age, expectations, screen size, and nature of the material and its application. Some specifics:

- User age - The de facto attitude is that the younger the user, the more comfortable they are with online material presented in a smartphone style - e.g. icons, cool colors, etc. It's not a bad way to think. Just as we went from the bland, gray look of the old HTML Help (CHM) output to the more tailorable browser-based WebHelp, and now HTML5, we're now going to the still more colorful smartphone style. My concern in this trend, however, is the risk of trying to force all material to fit into that style, as I said repeatedly during the webinar. I'm not sure that a guide to concrete mix standards would be appropriate in the same style as Angry Birds, but I expect to see someone try it.

- Expectations - Similar to my previous point but with the added points that we're providing less information as we expect users to be more up on things related to what we're documenting. For example, in the '90s, I wrote a lot of PC user guides and always included sections on the disk drives, how to use a mouse, etc. We don't do that anymore because we expect users to know those things. Companies are also reducing the amount of background material in their doc on the grounds that "if you don't know what a receivable is, you shouldn't be using our accounting software at all". That shortening of content makes sense but can be taken too far.

- Screen size - There's a lot as to what you can do with such a tiny screen. The best thing, in my opinion, would be some sort of gesture or head-movement navigation coupled with a predictive agent, but the attempts to date - BOB and Clippy - haven't been very successful.

- Nature and application of the material - An online help system for an accounting software package calls for different help than does Fruit Ninja, obviously, but the question is whether we make each help system look consistent with its application or with the platform on which the application runs.

I don’t know where I’ll go with this response but I’m interested in people’s thoughts…

Solution to XREF Format Problem in Flare

To the Flare class attendees who saw me demo the change in format of a cross-reference - to have it use hyperlink format for an online output but automatically convert to a page reference format for a print output like PDF - only to have it not work. I said I'd track down the problem and post the result on my blog.

It didn't work because I made the change correctly in the Print medium of the ws_ftp_styles.css file but forgot to specify that CSS for the output - e.g. I left the Master Stylesheet field on the General tab of the Target Editor set to Default rather than changing it to ws_ftp_styles.css. As soon as I changed the Master Stylesheet field to ws_ftp_styles.css and regenerated the PDF, the automatic conversion to a page reference format worked like a charm.

It's always that one little thing that you overlook...

Regards,
Neil

Responses to Questions From My "Four Paths to Mobile With Flare" Presentation

Thomas Z

Q: If I make a medium for another output is the second medium styles saved in the existing CSS style sheet?
A: Yes, they’re saved in the CSS under a section header that looks like @media... For example, all the custom settings that I made for my mobile medium are saved in the CSS under the heading @media mobile. That section and its first style entry look like this:

@media mobile

{
            h1
            {
                        font-size: 12pt;
                        color: #1e90ff;
            }

…plus any additional settings.

Craig P

Q: Do you do any kind of CSS reset for your projects?
A: I haven’t had the need to but it’s one of those things that’s on the horizon. (If you’re not sure what a reset is, try this article - http://sixrevisions.com/css/css-tips/css-tip-1-resetting-your-styles-with-css-reset/.)

Q: Mediums know mobile versus print, etc. How might screen size be handled?
A: The next step after mediums, officially called “media types” by the W3C, is “media queries”, also from the W3C, where you can actually set properties like screen size and related actions – e.g. “if screen size > 300 and < 600, do X…” kind of thing. If media queries aren’t near the top of the priority list for Flare 9, I’ll be shocked.

Q: What's the name of the first CSS book you mentioned? Authors?
A: “Cascading Style Sheets:Designing for the Web (3^rd Edition) by Lie and Bos. It’s not fully up to date as it was published in 2005 but, IMO, is the clearest book you’ll find on the subject and the best way to get the basics. Then plan to go online to read up on CSS3 and media queries and all the newer stuff.

Heather J

Q: It looks like you couldn't really display help along with the application. Do you see downsides to that?
A: There’s obviously a downside but that that’s only true if a given device won’t multi-task, in which case the help may have to be embedded in the application. Depending on what you’re writing help for, you may also be able to use Flare to create a WebHelp Mobile output and tie it “context-sensitively” to an app. I did this using a native app authoring tool called ViziApps, the one I mentioned, and Flare, and wrote a white paper about the process for MadCap last summer. I can send you a copy if you’d like. Let me know.

Sue A

Q: Could you have two mediums for mobile - phone and tablet? How do you add a medium?
A: You can have as many mediums as you want. (But remember that mediums let you set style properties but not adapt the content to the device size. For that, you want to get up to speed on media queries – see above.) To add a medium, open the Stylesheet Editor, click the Options pulldown on the right end of the Stylesheet Editor toolbar, select Add Medium, and name the thing. Select the desired medium using the Medium pulldown on the Stylesheet Editor toolbar. You can’t delete a medium via Flare’s interface. You have to open the CSS file and find and delete everything under the "@media mediumname" heading. It’s not a major problem but is inconsistent. I expect this to be corrected in Flare 9.

David W

Q: What do you recommend doing with tables in phone form factor and does CSS handle it?
A: That’s a tough one. First, I’d try to simplify my tables way down and conditionalize them for mobile output. Second, I’d grudgingly accept the fact that some tables are wide and have to be scrolled, just as I accept the fact that I sometimes find a landscape-formatted page in a printed book and have to turn the book sideways to read it. CSS does handle tables but it depends heavily on how well the device standard itself handles tables. For example, ePub doesn’t do a particularly good job, in my experience, with any table more complex than simple rows and columns. But check the particular standard you’re using.

Stephanie L

Q: how do I add a back button to my web mobile output?
A: Take a look at the Back and Forward “buttons” at the bottom of the canvas on the WebHelp Mobile emulator. Those act like the equivalent buttons on a browser toolbar. Let me know if you had something else in mind.

Answers to Questions From CSS Class at nSight on June 28

Here, a day late, are the answers to the questions from last week’s CSS class.


Re adding a non-scrolling region in a topic to create a non-scrolling table row to make sure the column heads for a long table remain visible as users scroll the table. What you do is create a non-scrolling region at the top of the topic (which would normally contain the topic title) and put the table row containing the column heads in that non-scrolling region. See the instructions at Mike Hamilton’s blog – see http://madcapsoftware2.wordpress.com/ and scroll down until you see the post entitled Adding Non-Scrolling Regions to Flare Topics. This works, but only if the table is at the top of the topic. If the table is further down, this won’t work since you can’t have a non-scrolling region within the body of a topic. However, you could put the tables in separate topics and link to them, in which case the column heads would be at the top of the topic. However, you’d have to do this consistently, or else label what you’re doing, to make sure that users don’t get confused as to why some tables are visible in the topic they’re reading but others are only available via a jump link.


Re Flare not showing style property changes in the Stylesheet Editor but showing them in the topics that use that style sheet? This may have been a one-time error as it seems to be working correctly now. If it happens to you again, either contact tech support or contact me directly and I’ll follow up for you.


Re where Flare puts a sub-class of an a tag, like my “littlepopup” example? It apparently does put it under the a tag rather than under the popup sub-class. It’s been almost five years since I created the custom popup tags, so my memory of where Flare put those sub-classes may simply have been incorrect.

Unofficial iPhone App for the STC ’12 Summit

Going to the Summit? (Or even if you’re not but want to get a feel for a conference-oriented app…)

Here’s a free iPhone app that will help you enjoy the Summit and illustrates some features that apps can provide. It also shows how GUI native app tools speed up and simplify authoring. I created this app using ViziApps (www.viziapps.com), one of the most flexible GUI app tools and one of the tools I’ll show in my Lightning Talk.

The STC ’12 Summit app lets you…

·    Get a list of Rosemont restaurants, and add your own entry to the list (for a social media element).

·    Take and annotate photos and add them to a public database.

·    Watch training or other videos, in this case an entertaining example from YouTube.

·    Check conference session times.

·    Send emails or SMS.

·    And more…

All this took under 40 hours to create, much faster – and cheaper – than working in code. It’s a powerful demonstration of how GUI authoring can bring mobile apps within any company’s reach. And ViziApps also supports native Android and iPad apps, plus web apps for RIM and Windows Mobile, and will soon support hybrid apps as well.

To try the app:

·    Install the free ViziApps app from the App Store on any iOS5 iPhone.

·    Start the app and log in under the username and password hwsdemo.

Want more information? Contact nperlin@nperlin.cnc.net  or see me in Rosemont.