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.

Single Sourcing with MadCap Flare – Part 4 – Flare Project Import

In previous posts, I noted that conditionality and placeholders are the foundations of single-sourcing but described them being used in single projects. What if you need to use the same elements in multiple projects? For example, if you want all projects from different authors to use the same product_name variable?

You can create those elements from scratch in each project but that’s inefficient. Or you can copy the control files for these elements from a main project and paste them into the child projects, but what happens if the author of the main project adds a condition? The main project’s modified control files must be recopied into each child project; it’s easy to forget or to copy the modified control file into the wrong folder in the child project. And it’s easy for a child project author to change the control file so that it deviates from the one in the main project, with a loss of consistency. There’s a better way, the Flare Project Import feature.

Conceptually, this feature is simple and much like copying the control files from the main project to the child projects. The difference is that when you copy a file from the main, or master project, to the child, the Flare Project Import feature maintains a link between the master project and the child projects and redownloads the file from the master to the child if a copied file has changed in either the master or child project. Consider the example below.

You decide that all projects must use the same CSS and Copyrights topic. So, you create a master project, the top box in the flowchart, and store the CSS and Copyrights topic there. (You could use any project as the master. However, that project may contain files that don’t apply in this scenario and are just clutter. It’s usually less messy to create a new project whose only purpose is to serve as the master.)

The authors of the three child projects then link to the master and download the CSS and the Copyrights topic to their projects. All other files in the child projects are different, but the CSS and Copyrights topic are identical.

Now, the author of one of the child projects makes a change in the copy of the CSS downloaded to that child project. Or perhaps the author of the master changes the CSS. As long as there’s a difference in the CSS, or the Copyrights topic, or any other shared file between the master and child project, Flare will redownload the version of that file from the master project to the child project and overwrite the version on the child project when the author of the child project generates the output.

The beauty of this feature is that it ensures consistency across the projects in which it’s used. You no longer have to worry about the authors of the child projects changing the color of the h1 style in the CSS or changing the wording in the Copyrights topic; the next time they generate their output, their changes will be overwritten by the official version of the file in the master project.

Better still, this applies to any file in a Flare project. You get invisible consistency across multiple projects. I consider this one of Flare’s coolest features and yet one of its least well-known because, unless you took a class or called in a consultant, you’d never know that the feature even existed. And the name, Flare Project Import, doesn’t really say what the feature does.

A few tips if you want to use the Flare Project Import feature:

•       Create a separate master project and name it “Master Project” to avoid confusion. You can use any project as the master project, but this has two problems. First, using a real project as the master means that there will be a lot of files that have no use in the master/child model and are just clutter and potentially confusing.

•       Document the feature to avoid creating “zombie” projects. The term comes from an old client who asked me to investigate why the CSSs in his group’s Flare projects kept reverting to some standard format even though the authors were deliberately modifying their CSSs. As the client said, it was as if the CSSs had become zombies. The problem was that a year earlier, an author had set up the Flare Project Import feature but didn’t document it, then left the company. So the feature was working perfectly but no one knew why or what to do about it. Avoid this problem, and spare yourself the need to call in a consultant, by documenting the project.

That’s it for Flare Project Import. Next up – conditionalized styles and CSS variables.

Single Sourcing with MadCap Flare – Part 3 - Placeholders

Another Flare feature that supports single-sourcing is placeholders, which Flare offers in two forms – variables and snippets. Placeholders let you insert the same content in multiple places in a project, such as multiple topics, and automatically change that content everywhere with just a few mouse clicks.

For example (from the introductory post), let’s say that you’re documenting a new product whose pre-release code name is Longhorn. You write the word “Longhorn” in hundreds of places throughout the documentation.

Then, just before release, Marketing changes the product’s name to Vista. You now have to search the documentation for all instances of “Longhorn” and change them to “Vista”. It’s easy – just do a search and replace.

But what if you misspelled “Longhorn” several times? A search and replace won’t fix that. You could do a fragmentary search and replace – search for “Long” – but that would give many false hits. 

Or, let’s say that you have to repeat the same set of steps in multiple topics. Easy – type the steps once, then copy them and insert them in the appropriate topics. But what happens when one of the steps changes? You have to find each insertion and change it. But how do you know where you inserted the material. You might keep track of the insertions but that calls for an unusual level of management. You could again search for the insertions but that might again bring up false hits. Placeholders are a solution in both cases.

Variables

The simplest placeholder is the text-only variable. In the first example, rather than typing the product’s name over and over again, you’d create a variable called, perhaps, productname, and set its definition (its value) as “Longhorn”. You’d then tell Flare to insert the value of the productname variable wherever you wanted the word “Longhorn” to appear in a topic or other file.

Then, when Marketing changes the product name, you’d simply change the value of productname from “Longhorn” to “Vista”. Flare then automatically changes the “wording” everywhere you inserted the variable. You don’t have to keep track of the insertions – Flare does that.

Variables are easy to create and use. What can be tricky is defining them. For example, what do you do if you need to use a variable as a possessive – if you want to say “Longorn’s features include…” Do you create two variables called productname and productname_possessive with values of Longhorn and Longhorn’s, or do you use the single productname variable and type “’s features include…” and insert the productname variable in front of the “’s”? Either approach works; you just have to define which approach to use and get all authors to agree.

Flare stores variables in a file called a VariableSet, with an extension of flvar, accessible from the Project Organizer pane. You can create multiple VariableSet files if you want to categorize multiple variables or simply break multiple variables into smaller groups.

Several points regarding variables:

• Variables usually have one value but you may need more sometimes for different outputs. For example, you might be generating US and Canadian outputs and have a variable called country. You specify that the value of that variable is US. But if you’re generating Canadian output, you’d want to change the value to Canada. You can override the US value on the Variables tab of the Target Editor but it’s a good idea to minimize the typing needed to specify output settings. The solution is to create the country variable, specify its value as US, but then click the third icon, Add Variable Definition, on the VariableSet Editor toolbar. You’ll see a second instance of the country variable, greyed out, and can now type the additional value, here Canada.
• How then do you tell Flare what value to use for a particular output target? On the Variables tab of the Target Editor, there’s a dropdown link to the right of any variable that has multiple values. Click that dropdown link and select the desired value.

• In addition to the standard variables, you can also specify date and time variables. One common use is to add a variable that specifies when the output was generated and that’s automatically updated. Click the second icon, Add DateTime Variable, type the name, such as Generated On, then click in the Definition field. When the Edit Format dialog box opens, type the format – click the I icon for help – then specify when to update the variable.

Snippets

Snippets are similar to variables but more powerful because they can contain anything you’d enter in a topic – text, lists, images, tables, links, formatting, and so on – including variables. In example two above, rather than typing the steps, copying them, and pasting them into the appropriate topics, you’d create a snippet called, for example, task1_steps. You’d then insert the task1_steps into the appropriate topics. When the time came to change one of the steps, you’d change it in the snippet itself. Flare would then automatically change the “wording” everywhere that you inserted the snippet. Again, you don’t have to keep track of the insertions – Flare does.

Each snippet exists in a separate flsnp file that’s accessible from the Resources folder on the Content Explorer. (You can put the snippet files anywhere you want within the project’s structure. I just find it simplest to store them in the Resources folder.)

Several points regarding snippets:

• You can create text snippets and block snippets. A text snippet consists of one paragraph of text or less. If you insert a text snippet on a new line or in an existing paragraph, it keeps its structure as a line of text. A block snippet consists of two or more paragraphs of text or other element followed by a return, such as a graphic. If you insert a block snippet on a new line, the snippet retains its paragraph structure. However, if you insert a block snippet in an existing paragraph, the block snippet paragraphs become run together.

• As noted above, a snippet can contain a variable. However, because you can assign conditions to snippets and variables, it’s possible to have a snippet to which you’ve assigned a condition to be excluded for a particular output but that contains a variable to which you’ve assigned a condition to be included for that same output. In such a conflict, Flare will default to an include so it will display the snippet because it contains the variable. The problem here is a management one; you’ll be wondering why that snippet displayed in the output when you thought you’d excluded it. Keep careful track of how your snippets, variables, and conditions interact.

• If you have numerous snippets and need to modify one, it can be hard to pick out the right one. The shortcut is to find one instance of the snippet, right-click on it, and select Open Link. This immediately opens the correct snippet file, saving you the trouble of hunting for it.

• Snippets can solve one limitation of variables. What if you want to end a step in a procedure by telling the users to “Press Enter.” You might create a variable called actionstep, for example, whose value is “Press Enter”. But what if you want the action step’s value to be “Press the Enter icon” followed by the actual Enter key icon. A variable is text, so that won’t work. However, you could create a snippet called actionstep that contains both the text and the icon.

As with conditions, common problems with placeholders are in design and management. We often give placeholders names that are not clear. The result? Other authors using the same set of variables or snippets won’t find what they’re looking for and wind up creating duplicates, which complicates project management. A related problem lies in not documenting the rules and logic to use if an author really does need to create a new variable or snippet. As with conditions, when you leave and a new author comes on the project, they may send the project off the rails because the lack of documentation makes it easy to make mistakes.

That’s it for placeholders. Next up – Flare Project Import, one of Flare’s coolest and least-known features.

Single Sourcing with MadCap Flare – Part 2 - Conditions

In post 1, I said that you can create one source of content and use it for multiple outputs, or select a sub-set of the content for each output. This is one of the foundation concepts of single-sourcing.

Let’s say that you create a sales procedure manual for use in the US and Canada. Some of the material applies only to the US, some applies only to Canada, and some applies to both. You could generate one manual that contains all the material and tell US users to ignore material that applies only to Canada and vice versa. A better solution is to extract the common material and the US material to create the US manual, and the common material and the Canadian material to create the separate Canadian manual.

This capability is driven by conditionality, one of the core features of single-sourcing.

Conditionality

To repeat my initial description from the first post, conditions are essentially categories. To repeat the US/Canada example above – let’s say you have to create a sales procedure manual for use in the US and Canada. Some of the material applies only to the US, some applies only to Canada, and some applies to both.

Conditionality lets you define categories of “US only” and “Canada only”. (Material common to both, or all, categories is always used so it’s not conditionalized.) When you generate the US output, you’d tell Flare to exclude any content categorized as “Canada only”. The output would contain the common material plus the US material but not the Canadian material.

You can apply multiple conditions to material. For example, say that the sales procedure manuals will not only include material specific to the US and the Canada but also slightly different material in the online and print versions. So, to create the online sales manual for the US, after applying appropriate conditions to the appropriate material, you’d tell Flare to exclude any material categorized as “Canada only” and any material categorized as “print only”. The resulting output would contain the common material plus the US material and online material but not the Canadian or print material.

In addition to controlling the behavior of topics, conditions can have wider effects. For example, say that you create a general table of contents that lists topics A, B, and C. The actual topic C is conditionalized as “Canada only”. When you tell Flare to exclude “Canada only” material when generating the US output, it excludes the topic and automatically removes it from the table of contents as well. And if topic A has a hyperlink that points to topic C, Flare automatically turns that hyperlink into regular text in order to avoid a broken link.

Conditions are very flexible. You can apply one or more of them to a topic or multiple topics and to any content within a topic, as finely as a single character. You can also apply them to any other project element – images, master pages, stylesheets, and even to other conditions. (Although I’d have serious reservations about doing that in real project.) This flexibility makes them very powerful but also requires that they be used and managed carefully.

The two problems that I most often see with conditions aren’t technical but rather ones of management and design.

• The first problem lies in not documenting the logic behind the conditions clearly or at all. When the initial author leaves and a new author comes on the project, they may send the project off the rails because the lack of documentation makes it easy to make mistakes when applying or invoking conditions.
  
• The second problem is the rapid growth of permutations as you add conditions to a project. With one condition, for example, there are only two permutations – include or exclude. With two conditions, however, there are four permutations – include/include, include/exclude, exclude/include, and exclude/exclude. With three conditions, eight permutations. And so on. It’s easy to get confused when to include or exclude multiple conditions in combination. And it’s easy to get confused as to when to apply them at all. The solution ties back to that for the first problem – document the logic behind when to apply conditions in a project and when to include or exclude different conditions in what combinations.

When might you use conditions in a project?

• Some uses are obvious – If you have to categorize material in a project as applying to the US or Canada, for example. A similar example would be to categorize material as applying to system administrators, professional users, or clerical users. When generating output for clerical users, you’d then exclude material conditionalized as “system administrator only” and “professional users only”.

• Another use is to document a project for new authors to reference or current authors to get up to speed after being off the project for a while. You can document a project in a separate Word document, for example, but that might get lost. A better approach is to document the project in topics that are part of the project and with authors notes inserted in specific topics. But you don’t want users to see this material, so you create an “author’s notes” condition, apply it to the topics and the in-topic notes, and then exclude that material when generating the output.

• Another use is to control which topics are made available to the reviewers. You could include all the material in the output and add instructions telling the reviewers to ignore topic 10 because it’s not finished. The problem is that some reviewers may not read the instructions, review topic 10, and give you scathing feedback about how topic 10 isn’t finished. You can avoid this by creating a condition called “not ready for review”, applying it to topic 10, and excluding the “not ready for review” condition on output.

That’s it for conditions. Next up – placeholders (aka variables and snippets).

GUI Information 4.0 Tools: A Proposed Feature Set – Comments – Final Version

This article first appeared in the Autumn 2019 issue of the ISTC Communicator.

In my article about a proposed feature set for GUI Information 4.0 authoring tools in the Summer 2019 issue of Communicator, I requested comments and feedback on the subject. I present those comments in this follow-up article as I received them, with no editing except to shorten a few threads due to space limitations. The comments appear below. I prefaced each comment, or set of comments, with the author’s name and Twitter handle in bold. (If the comments seem very disorganized, remember that this is a tweet-stream.) I also added a few comments of my own in response to a phone conversation with one of the commenters.

Here, with no further discussion, are the comments.

The Comments

Cruce Saunders @mrcruce

What should next-generation authoring look like now that we have 1,000s of permutations of media, content-types, browsers, channels, contexts, & formats? A difficult & valiant question to try to answer! Added some thoughts to a recent article. A thread for further comment.

Authoring rarely ever happened consistently in one GUI, even for small companies. In an enterprise, authoring is the single most diverse environment within content lifecycle process and technology. Content can be acquired in dozens of ways in a single department!

We should never assume an ability to conform large populations to a single GUI authoring platform. What typically happens in such enforcement scenarios: “cheating”. No GUI, especially one that wants to be so feature-rich, ever meets everyone’s needs.

So content gets built elsewhere and then PASTED into the GUI (often by someone else), where gets further manipulated. And one hopes, enriched with metadata. Or, publishing systems just get built around the GUI for various authoring groups that decide not to use it.

And the well-intentioned standard authoring regime falls into a chaotic mess of manual content transforms with no accountability or traceability. Most enterprises today live in some form of this mess.

Even when some smaller silos create some most consistent coherence (e.g. #techcomm), none of the related content sets are compatible. The answer, [A] believes, lies in aligning structural & semantic standard patterns across disparate authoring, management, & publishing systems.

All that being said, we do need to advance the state of GUI authoring. Vendors are working on this in product roadmaps. The biggest area of interest to me is essentially today’s attempts at “What You See Is Semantically-Markup Up Content”.

GUIs that *as the author types* suggest semantic associations derived from an organizationally-standardized taxonomy or ontology provider. This is effortless and invisible...machine-prompted, author-empowering.

The same sort of in-context editing, coupled with machine intelligence, can also help to prompt additional annotation useful for content targeting.

Another area of interest are GUIs in which a “sidecar” toolbar powered by artificial intelligence provides authors with in-context structured snippets for reuse and inclusion, based on the content of the material being authored.

Or, the sidecar suggests portions of text that might be reused by others. And providers authors the ability to apply metadata or discussions to individual snippets, or molecules, of content. Of course, these sidecar tools can be made to perform MANY other functions.

In my view, any vendor authoring product, and any related interface, needs to embrace schema application & portability to matter long-term. Companies desperately need to be able to move content around. But this is not possible without schema alignment across systems.

And that is impossible without authoring interfaces that incorporate a structural schema. I’d like to see more friendly blank-canvas interfaces (‘Word-like’) that incorporate an ability apply and manage schema-driven templates, beyond just standardizing styles.

We can see many attempts at schema-based GUI authoring, especially in the plugin market, where Word-to-DITA has been something pursued for some years.

One of the biggest areas of need, and most challenging, is the development of graphical user interfaces that support multiple variations of the same content within a single authoring process.

Personalization based on user type and state, and device or environment states, is something that many authoring processes need. And as we feed our customer experiences with ever-more contextual data, authoring for human or machine-meditated variation becomes essential.

The good news is this has also been pursued for some years, and the heuristics have been explored in multiple production environments — mostly in Customer Experience Management #cem platforms.

But there's plenty of room for innovation here, because "variation authoring" interfaces have not yet been perfected or mass-adopted. It's still a blue ocean space and vendors can distinguish themselves here.

There’s more to say, and much more to discuss, but the future of authoring is a very deep rabbit hole. And a worthy exploration. Take a look at more ideas from Neil Perlin (@NeilEric) in @ISTC_org Communicator or via the #info40 blog post.

James Mathewson @Mathewson_CS

The challenge is context. Content is only meaningful to the degree that it is relevant in context. How do you build an authoring system that helps writers grasp digital contextual cues and write relevant content using those cues? Modular content grows this problem exponentially.

Scott Abel @scottabel

Maybe our efforts would be better spent getting corporate leaders (those afraid of being displaced by disruptive innovators) to understand the need to become information-enabled. Authoring tools are created (and updated) in response to demand. The demand is simply not there — yet.

Neil Perlin (in response to Scott Abel’s point above)

A fair point. However, in the early days of help and the web, GUI tool development went on - often in odd or even wrong directions - even as the technology was spreading. Better IMO to become information enabled AND create the tools for doing so at the same time.

Cruce Saunders

The sea change is coming. Both customers and vendors are driving the evolution. One hand washes the other. Celebrate the innovators, wherever they sit.

Mike Atherton @MikeAtherton

+1 for context and structure. Something akin to a headless CMS is a good start, but rather than a bare bones experience, illustrative device and platform-specific templating to show authors how their work may appear.

And more importantly, since we're moving from a centralised publishing environment to distributed 3pp (AMP, Instant Article, other API) then explicit support and guidance ('recipes' if you will) from platform owners.

Aaaand a new mental model. The print analogy refuses to die and doesn't help separate content from presentation. A better analogy might be radio waves.

Neil Perlin (in response to Mike Atherton’s previous point)

I'll bite. Why radio waves?

Mike Atherton (in response to Neil Perlin’s point above)

Because the information transmitted is intangible, device-agnostic and everywhere at once. And because the same technology can emit frequencies designed for humans and frequencies designed for machines. I didn't say it was perfect :)

Cruce Saunders (in response to Mike Atherton’s point above)

Mike's 'radio waves' is similar to how I see content. Anything that can be available in multiple states, places, usages at one time is very different than tangible one-time published artifacts. It's 'information energy'. ;) But it's more durable even. So, we do need new frames.

Real device, type, user, context agnostic contextual preview or simulation is a holy grail. Even think it should be source agnostic. I actually believe there's an entire missing product category here. Rendering simulation & collab is something more than just another feature.

Mike Atherton

It's not even about being WYSIWYG 2.0 (i made that up), but what's missing from the structured content rhetoric is solid criteria for *how and why* to make specific structural choices. Bringing home context of use may help.

Actually @eaton

I think "next-generation authoring" has to assume that beyond highly data-driven fill-out-the-form stuff that CMS devs have already (kind of) solved… content will end up consisting of 1) Narratives, 2) Components, and 3) Assemblies/Aggregates…

…And also has to assume that workflow/responsibility for each of those modalities will require different tooling. You talk a little about this downthread but I think there's too much attention paid to UI and not enough to contextualied UX in the content editing/mgmt space

Then the big mind-blowing piece is that a huge percentage of what we would call "narrative" is spread across multiple pages/screens/artifacts for final delivery. Some of the journey/experience management stuff starts touching on that, but…

Mark Demeny @mde_sitecore

Great thread and summary from @NeilEric as well. It's a hard one to resolve (esp. over Twitter). Even putting aside the harder questions of content lifecycle, reuse, transformations for specific channels, etc. you get into questions of appropriate tools and interfaces very early.

You'll often hear "I wish my simple to use CMS was better at structured/headless content" similarly, you'll hear the opposite complaint of vendors that have a bias toward structured content but sacrifice page layout or authoring experience.

As I see it, there are 3 fundamental conflicts with content lifecycle; - Distributed vs. Centralized (with tools, author roles, team, geo etc.) - Structured vs. channel-specific - Creation agility vs. reuse (via better findability, analytics, etc. - more lean to the former)

And personalized/contextual content is a problem *layered across all of these*. It could be that a specific region, or an analytics team is responsible for acting on that - so I see that as not a distinct problem, but related to and complicated by the existing conflicts.

Jan Benedictus @JanBenedictus

Structured Content Authoring, Component Based Authoring etc. are often mentioned - by leaders ; but “what problem do we solve” is not articulated. We have to go from “strategic talk” to Tangible Benefits to explain Why. Today we are at @DrugInfoAssn to do so for Pharma #dia2019

Ray Gallon @RayGallon

Check out #nemetics as another vision close to these ideas. cc @toughLoveforx @ddrrnt

Two Additional Points of My Own

Mark Demeny noted correctly that I gave scant coverage to issues of governance and workflow and sign-off control.

I’ll add that I barely mentioned the effect of Information 4.0 on technical communicators. The increased technical and management complexity may drive some of today’s practitioners out of the field. That’s been predicted with every new technology and, to a degree, has been true but most practitioners adapt. What’s different with Information 4.0 is that even the base level of technical and management complexity is far higher than earlier disruptive technologies like word-processing in the 1980s and the web and online help in the 1990s.

Summary

The comments section may seem rambling because it largely matches the structure of the comments and responses. But I left it that way to show the wide range of thought about the technical, structural, management, and even philosophical issues. Once this article appears in Communicator, I’ll add it to the Information 4.0 Consortium blog and the Hyper/Word Services blog, and will add more posts as I get more comments.

So, now what? Is there a next step or has this just been an interesting discussion? That will have to be the subject of more discussion by members of the Information 4.0 Consortium. Stay tuned.

About the Author

Neil is president of Hyper/Word Services (www.hyperword.com) of Tewksbury, MA, USA  He has four decades of experience in technical writing, with 34 in training, consulting, and developing for online formats and outputs ranging from WinHelp to mobile apps and tools ranging from RoboHelp and Doc-To-Help to Flare and ViziApps. To top things off, he has been working in mobile since 1998 and XML since 2000, and speaking and writing about Information 4.0 since 2017.

Neil is MadCap-certified in Flare and Mimic, Adobe-certified for RoboHelp, and Viziapps-certified for the ViziApps Studio mobile app development platform. He is a popular conference speaker, most recently at MadWorld 2019 in San Diego, CA. Neil founded and managed the Bleeding Edge stem at the STC summit and was a long-time columnist for ISTC Communicator, STC Intercom, IEEE, and other publications.  You can reach him at nperlin@nperlin.cnc.net.