A Capsule Review of Flare 2022

MadCap’s new releases of Flare seem to fall into two categories, new features like QR codes and HTML5 output or major expansions of existing features. Flare 2022 falls into the latter category in three main areas.

Meta tags – Meta tags are elements that identify a file to help with retrieval or processing. For example, “title” is a meta tag – e.g., “find files whose title contains the word ‘barbecue’”. Flare has long supported meta tags, albeit on a simple level through the Description field on the Topic Properties tab. But 2022 adds a new Meta Tags tab and the ability to better add and control meta tags for SEO (Search Engine Optimization) and for Flare-specific tasks like managing micro content. And as powerful as the new meta tags feature is, it also seems to be a framework for future meta tag feature enhancements.

Micro content – 2022 has some major changes in the micro content feature. These include:

       “Containers” to let you categorize your micro content.

         The ability to tie your micro content to meta tags in order to more finely control what micro content displays under what conditions.

         More control over the “featured snippet” that displays in the results box when users run a search.

         The ability to pull micro content from all the micro content in a project or from selected groups via the new Knowledge Panel feature.

         And more.

Skins – MadCap has modified the Skin editor to change its look and behavior and add new features like proxies for maximum customization. There’s so much going on here that my advice is to read the description in the What’s New section of the help.

What I’ve written above is obviously totally superficial. That said, several broad observations:

·         Mechanically, the new features are easy to use once you know where they are in the interface. MadCap has generally been good with ease-of-use over the years and 2022 is no exception.

·         Conceptually, Flare continues to get increasingly powerful. I’d describe 2022 as equivalent to the original Flare times two, or more, since the micro content is equivalent to creating an entire content stream of its own that can be tied to the traditional topics.

 
As with any power features, you don’t have to use these new features. I suspect that many Flare users won’t. They’re overkill for most traditional projects. But if you need to support advanced searching or content segmentation, definitely look at and try out the new features.

·         Managerially (and I know I’m starting to sound like a broken record), winging it on your projects is increasingly infeasible. It’s always been important to plan and document your projects to keep them under control; it’s now absolutely crucial if you use any of these new features. (Blatant sales pitch – see my two-part webinar entitled “Why Documenting Your Project is Crucial to Staying Organized” in the list of recorded webinars at https://www.madcapsoftware.com/resources/recorded-webinars.aspx.)

All in all, an impressive release.

Review of MadCap Flare 2021 r3 and MadCap Central

MadCap just released new versions of Flare (2021 r3) and Central. In this post, I’ll take a brief look at the new features and speculate a bit as to where these tools are going.

The big new feature is the enhanced branching in Flare and Central. If you’re new to branching, imagine that you’re documenting version 2 of a product but you’ve been asked to document new feature X that will be included in a forthcoming version 3. A common way to do this is to copy the version 2 project, rename it version 3, and document new feature X in the version 3 documentation. Easy…

But what if engineering warns you that new feature X might not be completed in time for release of the version 3 documentation so you have to be prepared to remove that section. You can simply copy the version 3 project and name it “version 3 without new feature X”. You now have three Flare projects – version 2, version 3 with new feature X, and version 3 without new feature X.

To make things worse, what if you need to document new feature Y and add it in the two new versions? In this case, you might wind up with two more Flare projects - version 3 with new features X and Y, and version 3 without new feature X but new feature Y. Then you make some changes in version 3 without new feature X but with new feature y, then realize that you need to get these changes into version 3 with new feature X and new feature Y.

If your head is spinning at this point, that’s normal.

Authors often deal with situations like this, handling them using conditions. But conditions can quickly get complicated.  Branching can help. You can create separate versions of the documentation containing the different content, then merge the different content as needed. This can still be complicated but less so than trying to figure out the logic behind conditions that have often not been documented carefully.

For a good description of how branching works, see the Flare 2021 r3 webinar that MadCap first gave on January 26. Find it at https://www.madcapsoftware.com/webinars/new-releases-of-madcap-flare-2021-r3-madcap-central-a-walkthrough-of-whats-new-2

This webinar reviews branching enhancements in Flare and Central, plus using Central to perform topic reviews and builds and site creation, and enhancements to the topic filtering feature in Central. The description of branching starts at 2:31 in the webinar and ends at 12:52. It’s very well done and should get you up to speed on the concepts.

Some Thoughts on the New Features

From what I’ve seen of the software, MadCap has done a neat job of adding the branching features to Flare and Central and integrating the features across both. So, you can now do all your authoring and builds in Flare and simply use Central as a source control system, or do your authoring in Flare but build and control your source material in Central, or various combinations of both. It’s extremely flexible.

However, that flexibility means it can be easy to get confused over what tasks you’re doing in what tool. Because of that, I’d strongly recommend that any authors who use the new branching features write detailed cheat sheets that describe the process step by step.

There’s a bigger picture here as well. (What follows is my assessment of where MadCap is going. It’s not based on any information from MadCap.)

From the first, Flare has been both a tool and an environment to which MadCap attached new tools. For example, project analysis was originally done using the separate Analyzer tool until MadCap integrated Analyzer’s functionality into Flare via the Analysis feature. Generating analytics required using Google Analytics until MadCap added the analytics feature to Central. If you needed version control, you had to use third-party tools like Microsoft TFS, Git, or Subversion until MadCap added Central. Enhancement of the branching support in Central and Flare means that you can now do more and more tasks in the MadCap environment rather than having to mentally and procedurally integrate multiple tools from multiple vendors. In other words, MadCap is turning into a Swiss-Army knife vendor. What’s missing so far is large-scale governance features but the foundation is starting to appear.

I can see several effects from this.

•      Flare will become competitive with larger, more expensive commercial content management systems.

• ·    Flare will become competitive with expensive and custom content management and authoring systems offered by consulting companies. (To illustrate this, a few years ago I spent two weeks in Washington, DC getting a very large multi-national agency up to speed on using Flare to put its user manuals online. The client had been considering using a custom authoring system from a large consulting company at a cost of several million US dollars. Somehow, the client stumbled across MadCap and got the same results and better functionality, without being held hostage to the consulting company, for a fraction of the cost. I never did find out what the savings were but from the client’s expression, they were very large.)

• ·   Project management will have to become increasingly rigorous. Doing branching alone requires careful attention; handling branching across several authoring tools, even if well-integrated, requires additional attention. Basically, the days of “winging it” are coming to an end.

Do you need to upgrade to the new versions of Flare and Central? If you don’t do branching, then no. The previous versions of both tools will do fine. But if you do have to worry about branching or see it being a factor in the near future, I definitely recommend upgrading.

About the Author

Neil has over four decades of experience in tech comm, with 36 years in training, consulting, and development for various online formats and tools including WinHelp, HTML Help, CE Help, JavaHelp, WebHelp, Flare, and more. Neil is a frequent speaker at MadWorld and the author of several books about Flare, mobile app development, and project management.

Neil is Madcap certified for Flare and Mimic.  He provides training, consulting, and development for online help and documentation, Flare, Mimic, XML, single-sourcing, topic-based and structured authoring, and content strategy.  He can be reached at nperlin@nperlin.digitalspacemail8.net.

MadCap Flare 2020r2 – My Favorite New Features

 MadCap Software released MadCap Flare 2020R2 about two weeks ago, with new features ranging from those that add convenience to those that, in my opinion, indicate trends. In this review, I’ll briefly look at my favorites in this latest release. (For an overview of all the new features, see the “What’s New in MadCap Flare 2020 r2” video at https://www.madcapsoftware.com/videos/).

Micro Content Enhancements

MadCap continues to expand the micro content feature at a rapid clip. The most recent change is in the ability to format content differently when it’s displayed in a traditional topic versus when it’s displayed as micro content. Why do this?

MadCap’s example of using part of a set of content in traditional output and a slightly different part of that content in micro content is a good one. For example, you might not want to mention an option in the micro content in order to keep that material short in the more restricted space. Ditto using different formatting, different line spacing for example.

Assessment – From its inception, one of Flare’s major characteristics has been flexibility. That flexibility is further enhanced by this newest micro content feature. That feature also suggests future directions for Flare. (What follows is pure speculation.) For all intents and purposes, the micro content features are turning Flare into a two-track authoring tool. It can be used for “traditional” online content, with micro content integrated into that content, but can also be used to create (micro) content by itself, positioning Flare as an authoring tool for use in creating content for “terse” applications like VR, voice, or chatbots.

I have not yet had any Flare clients that make full use of the micro content features but I’ll be interested to see how that changes in the next few years.

“Sort at Build” Option

This is one of those seemingly trivial features that solves an annoying problem – what happens if several authors work on a list in the same topic and add, delete, or edit list items but don’t sort it before a build because that isn’t any one author’s job. The result is a list that’s out of order and doesn’t look correct, or that might even confuse readers. The sort at build option simply lets authors specify that the list should be sorted at build time by Flare itself, removing that task from the authors.

Assessment – “Sort at build” is a neat solution to the multi-author sorting issue. It also reflects a change in the authoring environment since it implies that multiple authors may touch the same material, which in turn implies the use of a source control system.

Salesforce and ZenDesk Enhancements

MadCap continues to enhance its ability to create output for use in these two environments. However, because these environments are so specialized, a detailed discussion of the enhancements won’t be useful here so I’ll simply note that the enhancements correct mismatches and problems between Flare and those environments.

Assessment – My experience is that Salesforce and ZenDesk authors are often less than happy with the authoring capabilities in those environments. MadCap’s continued improvement to Flare’s interaction with those environments makes it more likely authors can use Flare in place of the native authoring features.

Deprecated Features

I found two sets of deprecated features meaningful in both the trend and personal aspects.

The first is DITA output. DITA was introduced with a bang in the early 2000s as the answer for structured authoring but, outside of a small and specialized community, never took off within tech comm. MadCap gave DITA support a valiant effort but the deprecation is a recognition of DITA’s failure to effectively launch. (To my friends in the DITA space – let’s just agree to disagree.)

The second is the WebHelp output. WebHelp appeared in late 1997/early 1998 as a browser-based alternative to Microsoft’s HTML Help, the first HTML-based online help output. (The previous format, Windows Help, also from Microsoft, was based on RTF.) HTML5 began to supersede WebHelp in the early 2010s and is now dominant, as indicated by WebHelp’s deprecation by MadCap. Tempus fugit.

MadCap Flare 2020 – My Favorite New Features

MadCap Software recently released MadCap Flare 2020 and the May 2020 version of MadCap Central. As with past releases, the new features run the gamut from the unexpected and powerful to those that add convenience. In this review, I’ll touch on a few of my favorite features in this release of Flare. (For a look at all the new features, see the What’s New webinar that MadCap is presenting on May 13 (and likely to be found soon afterwards at MadCap’s web site).

Micro Content Enhancements

The biggest change is an enhanced micro content feature. MadCap Software has added support for conditions on micro content phrases in order to control what phrases are available for a given output. It also added support for conditions to control what micro content is seen when viewed in normal topics or as search results. Finally, it added support for variables in micro content, similar to “regular” variables. The result effectively creates a new development stream that can be used in parallel with regular topics or even in place of regular topics. If you’re already familiar with conditions and variables, using them with micro content won’t be too big a challenge. The biggest issue will be the expanded project management load.

Assessment – Flare is an extraordinarily powerful single sourcing tool. (See the six-part series on my blog at hyperword.blogspot.com for an overview of the single sourcing features.) These new micro content capabilities simply increase Flare’s single sourcing power. I don’t know any company that has made full use of all these features but between the existing features and the new ones for micro content, I can’t think of anything that I could not do.

There’s one more change to the micro content – creating context-sensitive Help at the field, or “object”, level. In the RTF-based help days, this was handled by “What’s This Help”. Over time, however, due to the effort that this called for on the parts of the help authors and the application programmers, field-level help largely disappeared. The enhanced micro content feature now supports field-level help by letting authors assign context-sensitive help IDs to micro content phrases. And rather than having to create separate topics for the field help, we can simply use text from a larger topic as the field help.

Assessment – I’m not sure how widely this capability of the micro content feature will be used because of the fall-off in the use of field help over the last 10+ years. But any company that wants or needs to create field-level help will welcome this feature.

Find and Replace Enhancements

Flare’s Find and Replace feature has always been very powerful. This enhancement boosts that power. The Find and Replace in Files tab is now split into two tabs – Find Text and Find Elements. The Find Text tab is largely the same as the Find and Replace in Files tab, letting you search for and replace text or search for and replace code in topics. But the new Find Elements tab enhances that by letting you search for types of items with conditions. For example, you can search for a category of item, including tag, class, style ID, inline formatting, or attribute. You can then specify what to search for within a category, such as a specific tag or class or a specific piece of inline format coding. You can then specify the replacement string. For example, from the examples in MadCap’s online help, you might remove a tip in all the topics. Or you might remove a Center class from all paragraphs in all snippets. Or you might remove local formatting from all topics in one folder. And so on.

Assessment – If you have to modify a project at the code level, or if you’re cleaning up the code from an old Flare project or a project from another authoring tool after import into Flare, the sheer power in this feature will put it at the top of your toolbox. My only reservation is that this feature is so powerful that you’ll have to carefully think through what you’re trying to do, and back up the project, before actually doing the work. (Both tabs have a Create Backup option which makes that easy.) I’d also recommend experimenting with it before actually using it.

Code Snippets

If you had to insert code snippets in your topics in the past, you probably did so in one of two ways. You might have taken a screen shot of the code and pasted it into the topic. This works but it’s impossible for readers to grab the code out of the topic to re-use it. Or you copied the code from another file, pasted it into the topic, and formatted it to make it stand out from the text. The new code snippets feature is like option 2 but better; it treats the code as an “object” that can be formatted in various language formats, and formatted for appearance, and adds a clickable “Copy” command that eliminates the need to select and copy the text like readers do now. Code snippets look attractive in printed outputs as well.

Assessment – This is a special-purpose feature, but it will come in very handy if you need to insert code snippets with syntax highlighting in your topics, such as in API documentation.

Collapsing and Expanding Tags in the XML Editor

If you create long topics with a complex heading structure, it can be difficult to keep track of where you are within that heading structure. Even with the structure bars turned on, different heading levels can start to look alike. Is that a Heading 2 or a Heading 3? The ability to collapse and expand sections in the XML Editor may make things easier. Simply click on the angled arrowhead to the left of the material – a heading, paragraph, etc. – to collapse that material. Clicking on the angled arrowhead again re-expands the material. Moving or deleting a collapsed head moves or deletes all the material collapsed under it. You can hide or show the collapse/expand indicators, just as you can hide or show the structure bars, by clicking the appropriate button on the lower toolbar of the XML Editor.

Assessment – This is a useful convenience feature.

New Plugin for ServiceNow

Flare added support for publishing to Salesforce and Zendesk in previous releases, a real benefit if you use Flare but have to create content to be published to those other systems. Flare 2020 adds support for publishing content to a third platform with the MadCap Connect for ServiceNow plugin. 

Assessment -- This is a very useful feature for ServiceNow users (as were the plug-ins for Salesforce and Zendesk) because they keep you within Flare’s single-sourcing feature set.

Summary

All the new features and enhancements are useful and continue MadCap’s tradition of pioneering. The enhanced micro content feature is the most impressive new feature in Flare 2020, but it also takes you further away from the “wing it” philosophy of development. A feature this powerful and wide-ranging needs careful planning and management to be used effectively. If you work in code, the enhanced Find and Replace feature is an unbeatable way to become more efficient – with the caveat that it’s so powerful that you’ll want to understand both the feature and what you’re trying to do very carefully before actually using it. And if you find yourself doing API documentation, or if you need to showcase code snippets in online and print output, you’ll appreciate the new code snippet editor.

Overall, Flare 2020 looks like a solid new release.

Contextualizing Our Content – One Step Beyond

On April 2, I gave a webinar for MadCap called “Contextualizing Our Content – Today and Tomorrow.” In that webinar, I briefly reviewed how traditional context-sensitive help (CSH) and responsive design work before discussing and demo-ing advanced contextualization. That involved customizing a Flare target in real-time, without regenerating the output, in response to simulated sensor data, such as a change in temperature reported by a temperature sensor. The idea was to show how content can be customized based on input from anywhere, not just from within the computer as in CSH and responsive design. The bigger idea was to illustrate an example of contextualization in support of the Information 4.0 concept.

I won’t describe that first webinar in any more detail. You can find it in the list of recorded webinars at https://www.madcapsoftware.com/resources/recorded-webinars.aspx#flare.

Several viewers asked what other criteria could be used to customize the content. Those questions lead me to do some further testing to see what other properties of the output could be modified without the need to regenerate the output – customizing the output in real-time by modifying a control file, saving the modification, and then simply refreshing the output. I didn’t test every possibility – this was a proof-of-concept test – but here’s what I found.

The input control data comes first. This could be external sensor data, as in the webinar, but, in theory, could be any kind of data from anywhere. One viewer asked if artificial intelligence data might work. I wasn’t able to test this but it should work. (If you’re the person who asked that question, please contact me if you’d like to discuss this further.)

The processing script comes next. I simulated this in the webinar by modifying the CSS file by hand but it should be possible to write a Javascript that captured the input control data and use it to create a new version of the control file (show.css in the webinar) or simply modify the control file.

The next issue, and the topic of this post, is what you can modify in the output. As the webinar showed, I could modify the content based on its conditionality. Because conditions can apply to almost anything in a Flare project, almost anything should be modifiable as long as the things to be modified are specified in a control file that’s in the Output folder. For example, I was able to modify the skin banner for tablets by changing the background-color under nav.title-bar in tablet.css in output > owner > HTML5 > skins > fluid > stylesheets. Similarly, I was able to modify the skin banner for mobile by making the same change but in mobile.css.

Here’s an example, first with the skin banner colors generated in the target output.

Desktop-sized:

Tablet-sized:

And finally, mobile-sized – i.e. phone-sized:

Now, here’s the same output but with the tablet and mobile banner colors set in tablet.css and mobile.css as described above. (I’m leaving the desktop-sized banner in red.)

Tablet-sized (the hex value for the silver is C0C0C0):

And mobile-sized (the hex value for the orange is ffa500):

It may be possible to control other elements of an output – as I noted above, this was more of a proof- of-concept than a complete test. But it does work. And as I noted in the webinar, this offers the ability to customize our outputs in response to a wide variety of environmental data. And it does so in real-time, which may open up industrial applications for which the traditional build process was too time-consuming.

It’s also just cool…

If you’d like to discuss this further, feel free to email me at nperlin@nperlin.digitalspacemail8.net.

Single Sourcing with MadCap Flare – Part 6 – Management

This post ends my series on single-sourcing features in Flare. It will be short and to the point…

The hardest part of using features like conditionality, placeholder, project import, and the like is keeping them under control. What happens when you don’t? Consider…

In the winter of 2017, I was hired by a company in Wisconsin whose project had about 20 conditions with about 1500 insertions. Unfortunately, the author who set up the conditions never documented how to use them. When she left, her replacements had no guidance for using the conditions so they guessed, with predictable results. The company could not be sure what they’d get from a build. I was hired to try to fix this situation.

I spent three days analyzing the project to figure out how the conditions were supposed to be used. At the end, I had to tell the company that I had no idea what the original author had done. My suggestion was to remove all the conditions, create a new set, DOCUMENT THEM, and then re-insert them. Not surprisingly, the company wasn’t pleased.

The only way to keep a project under control and future-proofed is to set formal standards for using single-sourcing (and other) features and document those standards and the project in general. As projects get larger and more complex, and as MadCap keeps adding useful new features, there’s no other alternative.

Good luck.

Single Sourcing with MadCap Flare – Part 5 – Other Features

My previous posts discussed the conditionality, placeholder, and project import features that provide so much single-sourcing power. In this post, I’ll discuss several lesser-known ones and one new one.

Conditionalized Styles

Most projects use one stylesheet but there are options. For example, you can create two stylesheets for use in a project and specify that stylesheet A should be used for online targets and B for print. The more efficient approach is to create one stylesheet and allow for stylistic variations in the targets by using the medium feature. Still another approach is to create one stylesheet and use the mc-conditions property in the Stylesheet Editor to literally turn a particular style on or off depending on the target.

You can find the mc-conditions property in the Unclassified property group if you’re looking at the styles by group, or alphabetically if you switch to the alphabetic listing.

CSS Variables

There may be cases where you want to apply the same property value to multiple styles. Consider color; you’d specify the same color for h1, h2, and h3. However, having to repeatedly specify the color makes it easy to make a mistake – typing the wrong digit in a hex-value color specification, for example. One solution is to specify the color in the body style, which propagates it down to the subsidiary styles, but this might still be a problem if you had to specify alternative colors for h4, h5, and h6. The CSS variables feature eliminates this problem by letting you specify the color in one variable and use that variable in different styles.

There are several steps involved in working with CSS variables – none complicated but detailed enough that I’ll recommend that you look at the CSS Variables topic in the Flare help.

Clean XHTML Target

We typically use Flare’s topic editor to create content for Flare targets but it also lets us create content – HTML files – for use outside Flare, in a wiki for example. However, external programs may trip over the MadCap-proprietary features. To deal with this, MadCap added the Clean XHTML target. Selecting this target generates the output using standard XHTML but strips out the MadCap-specific features. It’s not a widely-used feature, at least in my experience, but it does let authors add support for other programs without having to bring another tool into the picture.

Easy-Sync

It’s common for authors to have to import Word or FrameMaker files into Flare, converting them into topics in the process. The import can be a one-time task, after which edits are done by the Flare author in Flare. Alternatively, we may want the original author, who probably does not have Flare, to be able to continue to update the imported files in the original tool and have those change automatically flow into the Flare topics. The latter option is the basis for the Easy-Sync feature.

This feature is driven by two options on the Word or FrameMaker Import editor. Prior to version 2019 r2, we used the “Link generated files to source files” option on the first tab and the “Auto-reimport before generate output” option on the Options tab. (In Flare 2019 r2, these two options are combined in the Reimport group at the bottom of the Advanced Options tab.)

The Link option creates a link from the Flare project to the original Word or FrameMaker files. The Auto-reimport option tells Flare to compare the content from the previous import with the content in the files now. If they differ, Flare automatically reimport the Word or FrameMaker files, creating new topics and overwriting the topics from the previous import.

Easy-Sync lets us create nearly-automated publishing workflows. We create and maintain the content in Word or FrameMaker and use Flare as the publishing engine. The problem is that this feature overwrites the topics created by the previous import. For example, if we import a Word or FrameMaker file into Flare, breaking it up into topics in the process, and then add Flare features like links, those Flare features will be lost. So Easy-Sync is useful but it calls for careful project planning and management.

Responsiveness

One change affecting tech comm is the need to generate output to run on different devices – generally desktops, tablets, and phones. The output’s look may have to differ between the devices, and MadCap has been adding support for this with Flare’s responsive output and responsive layout features. (I gave a two-hour workshop on these features at MadWorld 2018.) Flare 2019 r2 adds a new feature in support of responsiveness, responsive conditions.

The responsive conditions feature adds responsiveness to conditions (sorry…). In prior versions of Flare, conditions were simply set to be included or excluded. The new responsiveness feature lets us specify that material be included or excluded depending on the output device. For example, we might use one graphic for a target aimed at desktop monitors but one with larger text for target aimed at phones. Or, my favorite example, automatically change the wording in a command from “Click the button” to “Tap the button” when generating output for a tablet or phone.

There are several steps to working with the responsive conditions feature, again none complicated but detailed enough that I’ll recommend that you look at the Responsive Conditions – Set By Media Query link in the What’s New section of the Flare 2019r2 help.

Summary

I hope these posts have given a sense of the range and power of the features that Flare offers for single-sourcing. Technically, they work well – the older features almost flawlessly after having gone through their birth pangs. The common problem with the features is managing them. That will be the subject of the last post in this series.