Tuesday, October 10, 2017

“Perfect vs. Good Enough” – Writing Quality in the Online Age

Part 1

In August 2009, Wired Magazine published an article entitled “The Good Enough Revolution: When Cheap and Simple is Just Fine” by the Wired Staff in the Gear column, 8/24/09, at https://www.wired.com/2009/08/ff-goodenough/.  Its theme – “cheap and simple beats perfect almost every time.” That article reminded me of a column I wrote in 2001 (“’Perfect vs. Good Enough’ – Writing Quality in the Online Age”) that discussed why technical communicators needed to change our definition of quality for the dot-com era.

On rereading, the 2001 column still seemed relevant. So, this column, part 1, presents the core points from the old column from 2001. Part 2 will revisit the 2009 column to present the core points of the Wired article and how they might apply to technical communication. Part 3 will revisit the issue of quality in the emerging age of taxonomies and semantic markup.

First, the old 2001 column, with my comments in italics.


I typically get one or two calls per week from prospective clients or people looking for writers with certain skills. Three years ago (1998), I got a call from a dot-com looking for a “content provider.” It was the first time I’d ever heard that title so I laughed and said “So you’re looking for a writer?” and was taken aback when the caller vehemently said “No! We don’t want a writer.”

I asked why. The answer – “… writers get too focused on perfection… we don’t have time for. If we wait until the material is perfect, our competitors will beat us to market. We do not need it perfect; we just need it good enough.”

I mentioned that conversation often. Two people used it as the basis for presentations in the Bleeding Edge stem at the 2001 annual (STC) conference – one discussing the issue from a writing perspective, the other from a tools perspective. Here, I discuss it from two other perspectives – trends and standards.


Four major trends affect the issue of writing quality:

·         Time-to-market is getting shorter.

·         Editorial positions are being cut back or eliminated in many companies.

·         Single-sourcing is becoming increasingly complex.

Single-sourcing isn’t new. If you used RoboHelp to create WinHelp and hard-copy in 1995, you were single-sourcing. But today’s single-sourcing technologies work best with rigorously structured content. We can no longer get away with “winging it”.

By supporting “good enough” as opposed to “perfect”, isn’t winging it exactly what I am calling for? But it’s not winging it if you write to a standard, just that that standard may call for “good enough.”

·         New competitors are entering our field.

Technical writing was once unglamorous and fairly low-paying. Today, companies are starting to view content – including documentation – as a strategic asset. That shift has attracted consultants looking for new business. But technical writers also want that work.

Outsourcing is a new competitor. Technical writers are upset over the perceived lower quality of outsourced material, and lost jobs. But consider the business perspective. If outsourced material has 50% of the quality but is written at 25% of the cost, a company may decide it’s a worthwhile tradeoff.

What are the effects of these trends?

·         Shorter time-to-market means less time to write perfectly or fix stylistic inconsistencies. (Without editors, there may be no one to fix or even notice those inconsistencies.) So we need to define the material’s look and style before the project starts. We need standards and consistency at a human level.

·         Increasing single-sourcing complexity means that consistency and simplicity are key to getting our material into a form for re-use. We need standards and consistency at a structure and format level.

·         Consultants often use formal methodologies to do their work and help sell their services. We need standards at the business level.

Defining A “Perfect vs. Good Enough” Standard

Few companies have formal writing standards. Even those companies that do often don’t use them. There seem to be two reasons for this.

·         There’s a lot of creativity and subjectivity in writing, so how do you define “good”?

·         Many writers dislike tools that measure writing quality. This may be due to a reluctance to have a creative process measured by machine, bad experiences with a tool, or antipathy toward a tool’s vendor.

But setting documentation standards can let us do two things:

·         Determine how to change our processes to compete with the new entrants in the “content” field and participate in emerging markets and niches.

·         Define measurable standards to help justify why technical writers should do the work, or at least participate in it.

These standards should do three things:

·         Establish a baseline. What is “perfect”?

·         Define acceptable and measurable deviations from the baseline. Formalizing such deviations – a maximum acceptable percentage of passive voice, for example – will help improve consistency.

·         List and describe tools, especially third-party tools, that let us measure the baseline and deviations.

These standards could be created in two ways.

·         Each company defines its own baseline, deviations, and tools as part of its style guide. However, many companies don’t have the time to do this.

·         An organization, such as the STC, could define a “perfect” baseline standard and make it available to members to use as is or to define their own deviations.


Because of the nature of writing, our profession has always accepted a subjective definition of quality. But changes in the market and technologies are starting to undermine that viewpoint. We’re going to have to confront this issue at some point. Now would be a good time, while we have time to do so thoughtfully and deliberately.

The old column ended here. In part 2, I’ll look at the core points of the Wired article and some ideas about their impact on technical communication.

Tuesday, September 19, 2017

Four Management Challenges in Implementing Information 4.0

Information 4.0 is a new concept but some of the technologies and methodologies that it encompasses are available and implementable today, albeit in early forms. But before that happens, Information 4.0 will face multiple challenges, just as online help and the web did in the 1990s.

In this post, I’ll discuss four implementation challenges on the management side:

  • Defining clear and consistently accepted terminology.
  • Demonstrating support for the company's strategic and business direction.
  • Dealing with problematic senior management biases.
  • Establishing and following standards, metrics, and analytics.

Defining Clear and Consistently Accepted Terminology

New technology often sounds like confusing gibberish.

  • Twenty years ago, and even today, there was confusion over “WebHelp” versus “Web Help”, for example. Because of that confusion, many companies bought the wrong tools, hired the wrong people, or just went off in the wrong direction.
  • Today, there’s confusion over the meaning of “mobile”. Is it an app? Responsive online help on a laptop and a mobile device? Something else? I recently consulted at a large manufacturing firm that brought me in to help assess its readiness to go mobile. One result was the discovery that the different divisions had totally different interpretations of the term.
  • Information 4.0 promises entirely new levels of terminological confusion. Is “molecular content” the same thing as a topic? What’s “dynamic” content? And so on.  

Until everyone agrees on the meanings of the terms being used for an Information 4.0 implementation, it will be difficult to show support for the company’s strategic and business direction. This means it will be almost impossible to do anything else. So any Information 4.0 effort needs an education component.

Demonstrated Support for the Company’s Strategic and Business Direction

Information 4.0 is cool. But that won’t be enough to build management support because management is typically being pressed to support other initiatives too, many also cool. It’s crucial to show, concretely, how Information 4.0 will support the company’s strategic and business direction. That’s going to require careful analysis of the company’s operations beyond technical communication.

Dealing with Problematic Senior Management Biases

Even if senior management supports an Information 4.0 effort, we may encounter biases that affect that support. (In the early days of business computing, managers didn’t want to use computers because that involved typing and the bias was that typing was secretarial work. Renaming “typing” to “keyboarding” got past that bias and made typing – on a computer – cutting edge.)

For example, it will be crucial to present Information 4.0 as dealing with “content” and “user support”, not “documentation”. No one cares about documentation. But despite your efforts, management may still view Information 4.0 as documentation-focused, not realizing that “documentation” today is more a combination of content creation and programming. If so, it will be hard to get management support. By way of illustration…

I was contacted by a company whose online help was created using a long-dead version of RoboHelp. Users complained that the search didn’t work well and there were problems in the code. The company wanted to convert the help to Flare to get better search results and clean up the code to future-proof the content, both supposedly good things.

The company turned down the proposal on the grounds that it was too expensive. The problem was that they saw their help as documentation rather than as a strategic resource and gave it a far lower priority. The upshot? Their staff would do the conversion. Unfortunately, the staff was bright but didn’t know RoboHelp, Flare, or code so the effort was likely to be slow and inefficient at best.

In that tale is an example of how management bias may harm even efforts that management wants. And Information 4.0 is far more complex and unfamiliar than online help, so bias is likely to be still more of a problem.

Standards, Metrics, and Analytics

In the mid-1990s, online help and the web were so new that few companies had standards or metrics by which to measure them. And analytics barely existed.

Today, however, getting management support for an Information 4.0 effort will require showing support for your company’s business and strategic direction. (That may not always be the case. In 2002, I spoke with two people from an aircraft builder whose CTO was so impressed with mobile that he directed that it be implemented on the manufacturing floor without cost-justification. So you may not always have to demonstrate support, but it’s the safe way to bet.)

Demonstrating that support often requires quantitative data, ideally numbers that translate to increased revenue or reduced expenses. Information 4.0 is so new that few standards exist, and thus few metrics or analytics. Yet Information 4.0 has a lot in common with today’s online help and web efforts, and may be able to use some of their standards and metrics. The biggest problem I’ve found with metrics for any purpose, let alone Information 4.0, is resistance from people who don’t want to be measured.


Information 4.0, like any new technology, is fun to speculate about and fulfilling to help emerge. There are many interesting challenges on the development side and the impact on tech comm. I’ll look at these in later posts.

But none of them matter if you don’t sell management on the idea in the first place.

Wednesday, September 6, 2017

We’re Going Mobile! Great! But What Does That Mean? And Are We Ready?

So, your company has decided to take its documentation mobile. Great! But has the company considered:

        What does “mobile” mean? People often assume that “mobile” means an app on a smartphone but does everyone share that definition? If not, different groups can wind up going in different directions.

        How do you plan to go mobile? Creating responsive versions of the documentation, converting the online documentation to an app, creating a “true” app, or something else?

        Should your content authoring practices change? You may be authoring in ways now that violate good practice, such as local formatting in Word, but that have been working until you decide to go mobile.

        Will your business practices support an organized and maintainable mobile effort? If not, the move to mobile is likely to be a one-off that wastes resources and loses management’s support.
In this post, I’ll briefly discuss these questions. The post is based on the “We’re Going Mobile! Great!...” presentation that I gave at the STC annual conference in Washington, DC in May, 2017 and the TCUK conference in Nottingham, England in September 2017.

What Does “Mobile” Actually Mean?

It sounds silly, but poll everyone involved to make sure they’re defining “mobile” the same way. Often, they may not be and the result can be chaos if you’re trying to set up a company-wide mobile strategy.

How Do We Plan to Go Mobile?

There are three primary approaches – responsive output, converting online documentation to an app, and creating a “true” app.

1 – Responsive Output

Responsive output means creating one online document or web site that can detect the properties of the device on which it’s displayed and automatically reformat itself accordingly. This can be very useful because if your material has to be displayed on desktop PCs, tablets, and smartphones, you only have to create one output rather than one output for each device.

And, depending on your authoring tool’s features or your code skills, you can not only change the screen layout, such as collapsing the menu, but change the layout of the content, such as changing from a horizontal to a vertical format, and even change wording, such as changing “click” when the material is displayed on a PC to “tap” when it’s displayed on a mobile device. All automatically.

2 – Converting Online Doc to An App

Because so much online documentation is primarily text and graphics, we tend not to think of it as being suitable for an app. Yet many apps are largely text and graphics. Check out the Messier List and Encyclopedia Britannica apps for example.

How can you convert your online documentation to an app? Two quick options:

·        If you use Flare, you’ll use the cloud-based PhoneGap Build (https://build.phonegap.com/). See my May 2017 post on MadCap’s MadBlog at https://www.madcapsoftware.com/blog/2017/05/18/convert-madcap-flare-target-mobile-app/.

·        If you use RoboHelp 2015+, you’ll use the built-in PhoneGap (http://phonegap.com/). For information, see this post by Robert Desprez – http://tinyurl.com/h2y27o2.

·        For general information, see PhoneGap Essentials by John Wargo.

Not everything will convert smoothly. Popups convert to hyperlinks. Some head styles converted to italic when I converted a RoboHelp 2015 project, though this may have been fixed in v. 2017. But the main content, structure, and features converted surprisingly well.

3 – “True” Apps

Need the look and features of a “true” app? The last few years have seen the appearance of code-light or code-free app development tools. These are sometimes referred to as DIY (do-it-yourself) app tools, or categorized by Forrester Research as Rapid Mobile App Development (RMAD) tools. (Look for a future post on the subject of RMAD tools.)

RMAD tools have two uses for the purposes of this discussion.

        Let non-programmers create apps.

        Let programmers create apps by making the interface creation, workflow, and data access tasks simpler than working in code in order to free up time to concentrate on the code-heavy tasks.

By way of disclosure, I’m certified in one RMAD tool called ViziApps (www.viziapps.com). For a list of other RMAD tools, see “10 simple tools for building mobile apps fast” at http://tinyurl.com/hzz4j5c

Why create true apps rather than using responsive output or converting your help to an app? Two primary reasons.

        User expectations – If you say “app” to most smartphone users, they’ll have expectations about the look and features that responsive output or converted help may lack.

        The need for new capabilities such as location or orientation sensitivity, a built-in camera, RSS feeds, transaction processing, and more.

What Effects Might Mobile Have on Your Development Practices?

If you plan to make your content mobile in an efficient and maintainable way, you may need to make some changes in how you create and maintain that content. Some examples:

        No more hacks – Hacks may be impressive but they’re often a bending of good coding practice that can be hard to maintain and may not work as you upgrade your authoring tools or code version. As someone once said, “A hack is a one-off; good coding is forever.” Eliminate existing hacks and make it a policy that new hacks are not permitted.

        No more local formatting – Local formatting is inefficient and overrides the styles in your CSS. This is not a not a mobile issue per se, though it bulks up files and may slow downloading. But it’s just bad coding practice and may break something in the future.

        Replace local formatting with styles, which may mean cleaning up your CSS.

        Rethink your writing style. Make it shorter, more granular, and more focused.

        Eliminate excess content.

        Tables can be hard to fit into small screens, so rethink what purpose your tables serve and how to use them. If your tables are containers for multiple content pieces, only one of which is used at a time, can you replace your tables with lists of links or searches?

        Consider changing navigation – Indexes are being replaced by search. Does this affect you?

        Use up-to-date, commercial tools – Look for tools that offer new features like responsive output and get rid of outdated tools. Be wary of tools with proprietary features that may not translate going forward. If you use such tools, be wary of leap-frogging multiple versions to get up to date or switch to a different tool.

Do Your Business Processes Support Mobile?

You can be okay regarding definition, technical approach to conversion, and cleanup of development processes and still have the move to mobile fail because it isn’t supported by your business processes. Some examples:

        Management buy-in – Have you given senior management sound business/strategic reasons for going mobile in order to justify the effort and build long-term support? If not, the effort will die.

        Training – Have the authors been formally trained in the correct and effective use of their tools? Peer-to-peer training may work if the trainers are experts, but too often this simply promulgates bad practices.

        Standards – Have authoring standards been clearly defined, promulgated, and enforced across all authoring groups? Without such standards, it’s almost impossible to share content between groups and projects.

        Development metrics – Are there clear, focused metrics?  If not, it’s very difficult to identify weaknesses in the development processes. Something as simple as time-per-content-unit is a convenient way to keep track of the effort and resources required.

        Usage analytics -  Do you collect and analyze usage data to find out what users, if any, are using what material? Without such data, you’re basically throwing your mobile content into the darkness and hoping for the best.

        Governance – Is there any formally defined process for managing the workflow and ensuring that material meets internal and any external requirements?

        And more…


It’s easy to go mobile – buy an authoring tool, figure out how to use it, and convert your content to a mobile format. Unfortunately, this approach can be very inefficient and lead to results that are neither maintainable or reproducible.

Similar problems arose in the early days of online help in the mid-90. But back then, much of the effort was experimental, user expectations were minimal, and schedules were loose. Today, “mobile” is a much more culturally accepted form of presenting content, which means that user expectations have been conditioned by a decade of smartphones, and users want their mobile content now.

Proper planning before going mobile will help your company better meet those expectations.

Tuesday, September 5, 2017

Beyond the Bleeding Edge Returns

Beyond the Bleeding Edge was a conference session that I ran at the STC’s summit from 1999 until 2014, and a column I wrote for the STC’s Intercom magazine from 2000 to 2015. The goal was to introduce technologies that were new to tech comm – on the leading (or bleeding) edge and beyond – such as XHTML, WSDL, JavaHelp, haptic interfaces, the W3C RDF metadata standard, and more.
The Bleeding Edge is now Hyper/Word Services’ technology blog. Look for a new post every 3-4 weeks on various technologies, tools, and methodologies, with a focus on mobile content and the Information 4.0 concept, plus whatever else seems appropriate.
Technology is fun!

Tuesday, April 11, 2017

Welcome to MadCap Central

NOTE 1: This article was originally published in ISTC Communicator, Spring 2017.

NOTE 2: Since I wrote this article, MadCap has released v. 2017 of Flare, which does not change the interaction with Central, and a new version of Central which adds support for Slack. Central's basic concepts and features remain the same however.

If you’re a MadCap Flare user, you’re likely to have run across two issues with your projects.

Issue one has to do with safeguarding your projects, getting them off your local PC and on a server to avoid losing the project files if your PC is damaged, and making them available to additional authors. The traditional answer is to get a version control system like Subversion or Git, but what if you don’t have the budget or IT support? From my training and consulting experience, many MadCap Flare shops are in this position.

Issue two is project management – how to keep track of the projects, tasks, and staff needed to create your projects. Many authors keep project to-do lists but they’re hard to manage and easy to lose, even for a single project with one author. It becomes still more difficult if you have one project with multiple authors, or multiple projects. How to keep track of everything?

MadCap Central is MadCap Software’s answer to both issues. MadCap Central combines project management and version control in one surprisingly easy-to-use package that integrates with the latest version of Flare, version 2016 r2. (If that number seems odd after years of integer versions like 10 and 12, it’s because MadCap has adopted an Agile release policy that promises incremental releases with new features and bug fixes several times a year.)

Let’s take a look at how MadCap Central offers version control and project management.

Version Control Features

Look at Flare 2016 r2’s View ribbon and you’ll see the new MadCap Central icon. Clicking it opens the MadCap Central pane where you can log in to MadCap Central. (You can also click an icon on that pane to quickly open the MadCap Central portal page in a browser and log in there.) Once you’re logged in, you’ve got several options from the MadCap Central pane’s local toolbar:

The principal options are:
Upload this project to MadCap Central – Click  to move the project into (bind it to) MadCap Central. Once you do this, you’ll see a Source Control item on Flare’s menu. Clicking that item opens the Source Control ribbon, shown below, which lets you control the project’s interaction with MadCap Central.

 At this point, you’re using MadCap Central like any version control system.

Remove MadCap Central Bindings from Project – Click  to remove the link from Flare to the project in MadCap Central. You’d do this if you want to take the project back to local status for some reason. Removing the binding from a project does not remove it from MadCap Central; instead, it simply removes the link between MadCap Central and the project.

Import a project from MadCap Central – Click  to download a copy of a previously uploaded project. You’d do this if you hired new authors and need to give them access to the project, or if an author’s PC crashed and the project has to be re-downloaded onto the new PC.
Upload latest local files to MadCap Central – Click to move any changes made on the author’s local PC to the version of the project in MadCap Central. You’d do this to update the version in MadCap Central with the latest local changes.
Open the MadCap Central portal – Click  to open MadCap Central in your browser. You’d do this to quickly access MadCap Central’s project management features.

So MadCap Central is actually replacing a traditional version control system. And you can use it to actually host your output. So binding a project to MadCap Central and managing the version control aspect really does seem to be this simple.

Three points to bear in mind:

  • MadCap Central is in public beta as of the date of writing this article – mid-December 2016. My experience is that everything is working smoothly but, as in any beta, some oddities may emerge.
  • MadCap Software plans to provide a gigabyte of storage for each MadCap Central subscription, shared among the users associated with a subscription. That figure may change depending on the result of the beta.
  • MadCap Software hosts MadCap Central, handling all server administration for you and effectively acting like a shadow IT department. This saves you the cost and effort of hosting a version control system yourself. Note that if you have a mandate to use a version control system that’s already in place, you can use MadCap Central in conjunction with other tools like Subversion or Git.

Project Management Features

Once you bind a project to MadCap Central, you can access a wide range of project management features.

The Home page features that let you display a dashboard, shown below, containing various widgets with information about aspects of all or selected projects or users.

The first release lets you select from eight pre-defined widgets. (Future releases may let authors create their own custom widgets.) You can manage the widgets and filter the information they show.

The Project page has features that let you get a high-level view of all projects stored in MadCap Central, showing the team members and individual users assigned to projects, project status, build and publishing history, and more.

A build management pane lets you see the targets for a project and build one from Central.

The Tasks page has features that let you define tasks with priority levels, the person responsible for the task, start and end dates, and more. You can see these tasks in a task board, shown below.

You can also see the tasks in a calendar view to help you plan your schedule. You can also filter and archive tasks in various ways to focus on what’s important at a particular time and to be able to go back and review what you did for a project post-mortem.

The Users page lets you invite authors into MadCap Central, set their permissions, specify projects and teams in which they can participate, and more.

The Teams page lets you specify what users belong to what teams, send messages to team members, keep tabs on the activities performed by members of a team, and more.

Basically, there’s no one specific way in which to use MadCap Central as a project management tool. Its features let you view projects in many different ways depending on what information you’re looking for. (This is similar to MadCap’s Analyzer add-on tool. Analyzer offers many options; the ones you use are entirely up to you.)


MadCap Central is a well-thought out product that offers easy-to-use project management for Flare projects and an equally easy-to-use alternative to traditional version control systems. It will also serve as a platform for future enhancements to the project management and version control features. In summary, MadCap Central will add control and safety to your Flare projects and is definitely worth a look.

One obvious question – is MadCap Central worth it if you’re a sole author working on one project? In my opinion, yes, if only for the version control system aspect. In fact, that may be the strongest selling point if you’re a sole author because you probably lack the time to deal with the complexity of installing and managing a traditional version control system. The fact that MadCap Central does that installation and management for you is a huge time saving.

Note – For a more detailed look at MadCap Central, watch the introductory webinar. Download it from the list of recorded webinars. Go to http://www.madcapsoftware.com/resources/recorded-webinars.aspx#central and look for “Introducing MadCap Central: An Overview + MadCap Flare 2016 r2” dated November 17, 2016. There’s a second one as well, dated December 15, 2016.

About the Author

Neil is president of Hyper/Word Services (www.hyperword.com) of Tewksbury, MA.  He has many years of experience in technical writing, with 32 in training, consulting, and developing for online formats and outputs ranging from WinHelp to mobile apps and a broad range of tools.

Neil has been using, training on, and consulting on MadCap Flare since 2004 and is MadCap-certified in Flare and Mimic. He is an STC Fellow, founded and managed the Bleeding Edge stem at the STC summit, and was a long-time columnist and contributor to STC Intercom, IEEE, ISTC Communicator, and other publications.  You can reach him at nperlin@nperlin.cnc.net.

Monday, July 13, 2015

Farewell to “Beyond the Bleeding Edge”

The Bleeding Edge was a series of presentations at the annual STC conference (now the Summit). Its goal was to address cutting-edge technologies and methodologies that emerged too close to the conference to be addressed by the standard presentation proposal route. I proposed it after the 1998 conference after hearing comments that there weren’t enough advanced sessions. After approval by then STC-president Mark Hannigan and Assistant to the President Deborah Sauer, I launched the Bleeding Edge in 1999. I ran it from 1999 to 2014 except for a two year hiatus due to some organizational issues in 2008 and 2009.

Bleeding Edge presentations covered JavaHelp coding, XHTML, haptic interfaces (IBM sent a speaker from London, as I recall), the W3C RDF metadata standard, search engine optimization, XSLT, on-demand publishing, and similar topics. My Beyond the Bleeding Edge column in STC Intercom came out of the Bleeding Edge. The Bleeding Edge also spun off a “standards watch” session, with speakers discussing developments in bodies like the W3C and IEEE, and several “standards watch” columns in Intercom.

The Summit organizers decided not to run the Bleeding Edge in 2015 because they thought the Summit’s technical level had risen to the point where the Bleeding Edge was no longer needed. From what I saw of the presentations in Columbus, I agree. Although I’ll miss the Bleeding Edge, its demise is a positive sign for the Summit overall.

My thanks again to Mark Hannigan and Deborah Sauer, and to all the presenters over the years who did such an outstanding job of helping keep STC on the cutting (or “bleeding”) edge.

Sunday, March 22, 2015

What’s New in MadCap Flare 11?

New versions of MadCap Flare combine powerful extensions to existing features and new features that go in unexpected and intriguing directions. Flare 11, released on March 17, continues this tradition. In this post, I’ll look at my favorite changes. (There’s far too much new to cover in one post. The What’s New Guide, http://docs.madcapsoftware.com/FlareV11/FlareWhatsNewGuide.pdf, is 350 pages long!)

By way of a brief introduction, I’m certified in Flare and Mimic and do a lot of training and consulting for MadCap so I’m not only a reviewer of Flare but a heavy user.

Extensions to Existing Features

User-Defined Macros

Help authoring often requires authors to perform the same set of steps over and over, such as applying a style to a series of paragraphs. It’s tedious work. Flare authors have been asking for a macros feature that lets them record the steps and play them back with a few clicks. This feature is now available in the Macros group on the Tools ribbon.

To use this feature, click the Record button, name the macro, and do the steps. When finished, click the Stop button (the renamed Record button). Select a macro to run by clicking the Playback button.

This feature is easy to use mechanically, but recording a macro records all your steps – mistakes too. So it’s hard to whip off a new macro on the fly unless it’s a simple one. But once authors get used to having to work carefully, macro creation is pretty simple and very useful.

Word Import Enhancements

Many Word users focus on producing documents that print smoothly, without regard to whether those documents can have a life beyond printing. Because of that, Word documents often have problems that cause trouble when imported into Flare – two in particular, both dealt with in v.11.

  • Authors who need to insert a screen shot in a Word document often just capture the screen and paste it into the document, but never save the screen as an image file.  This means Flare doesn’t know what to call the image file on import so it uses a random number for the file name, such as 0600001.jpg – technically correct but not very helpful.

    V. 11 partly fixes this. It names the pasted-in (embedded) image file after the name of the topic in which that image appeared. So Flare calls an embedded image in a Texas topic Texas. jpg, for example. This is a partial solution because if a topic has many embedded images, Flare creates multiple images files with names like Texas.jpg, Texas1.jpg, etc. Authors still have to figure out which image is which, but images being named after the topics that contain them simplifies the search.
  • Word authors who create tables usually calculate the number of rows required, then add a row for the column heads. Flare can designate a row specifically as a header and format that row using the Header settings in the Table Stylesheet editor. However, when you import the Word document into Flare, it has no defined header row. The solution has been to open Flare’s Table Properties dialog box and change the Number of Header Rows from 0 to 1. You then have to move the headings in the original heading row into the new, defined Header row and delete the old and now empty original header row. Easy but cumbersome.

    V. 11 fixes this. It can automatically convert the first row of a Word table to a Flare Header row. You’ll still have to clean up tables that have multi-line headers but single-header row tables will import far more easily. This feature is on the Options tab of the Word Import editor.

Cross-Reference Enhancements

I’ll start with a brief review of cross-references for Flare authors who aren’t familiar with them.

Cross-references are similar to hyperlinks but add two benefits.

  • They’re “aware of” their target title and change their wording if the title changes. For example, say you create a cross-reference to a topic called Grinder. The cross-reference wording will say ‘See “Grinder”’. If you then change the target topic title to Hoagie, the cross-reference wording automatically updates itself to ‘See “Hoagie”’. This eliminates the manual editing needed if you use traditional hyperlinks to point to a target topic whose title may change.

  • They can change their format to a page reference when output to a print format. For example, a hyperlink like ‘See “Grinder”’ is fine as a clickable link in online output or a print output viewed online, such as an on-screen PDF. However, if readers print the PDF, the link obviously doesn’t work – the reader can’t tell what page the link pointed to. This means the reader has to refer to the table of contents or index to locate the target of the reference. But with a cross-reference, the format automatically changes from a hyperlink-style like ‘See”Grinder”’ to a print style like ‘See “Grinder” on page 45’.

So what’s new with cross-references in v. 11?

Cross-reference granularity in prior versions of Flare could be too coarse. For example, a cross-reference might point to a target that wound up on the same page as the link. The result? A reference that said ‘See “Grinder” on page 45’ when the original link was also on page 45. In v.11, the cross-references are more sensitive to the context of the target. For example, if the target is on the same page as the link, the cross-reference wording is ‘See “Grinder” above” or ‘See “Grinder” below’, depending on the target’s position. If the target is on the previous or next page, the wording is ‘See “Grinder” on previous page’. And if the target if further away, the wording is ‘See “Grinder” on page 45’. The result is more realistic.

YouTube and Vimeo Movie Insertion Through the Flare Interface

Flare makes it easy to insert multimedia, such as Flash or HTML5 movies, into topics, but the assumption has usually been that the movies are part of the project. However, more authors use YouTube or Vimeo as movie distribution mechanisms or just want to link to movies from those sites, and v.11 makes it easy to add movie links directly from the web. Authors can either embed a movie in a topic using the Insert > Multimedia > YouTube/Vimeo option, in which case authors can set options like automatically starting a movie when a reader opens the topic, or linking to a movie using the Insert > Hyperlink option, in which case the reader must physically start the movie.

Interesting, Intriguing, and Sometimes Unexpected New Features

In no particular order (they’re all interesting)…

TopNav HTML5 Output

In 1989, starting a help system opened a single pane window that showed the topic. No navigation pane displayed until readers clicked a “Help Topics” button on the “button bar”. That opened the navigation pane in a separate window. Together, the two windows looked like this, navigation on the left, topic on the right:

In 1995, the release of WinHelp 4 introduced connected navigation and content panes that looked like this example (from Microsoft’s HTML Help) and was called the “tri-pane” window.

So the familiar tri-pane has been with us for 20 years. In recent years, however, Flare authors have been asking for a more web-like look. Some authors created it by hand by working directly in the code. In response, MadCap introduced the TopNav HTML5 output. TopNav has many options but the basic effect is to replace the tri-pane with something like this:

TopNav takes the table of contents and places it horizontally along the top of the window. Some layout elements have also been made individually selectable, so authors can create interfaces like this:

The introduction of the TopNav output has several ramifications. Three immediate one are:
  • TopNav looks cool but may not work for projects that have many level 1 TOC headings because too many headings will visually clutter the TopNav output.
  • TopNav adds many skin options. Using those options calls for more deliberate planning than the traditional tri-pane.
  • By breaking away from the traditional, documentation-related tri-pane look, TopNav may allow technical communicators to move into new publishing areas beyond traditional help.

By offering an immediate change in how we design online help and documentation, I consider TopNav to be one of the most meaningful new features in v.11.

Doc-to-Help Import

For some companies that create Word-based documentation and just need to put it online, Flare may be over-powered. In response, MadCap bought GrapeCity’s Doc-To_Help authoring tool in January. The idea was that authors who didn’t need Flare’s power could use Doc-To-Help instead. However, if those authors decide that they need more power, they can import the Doc-To-Help project into Flare.

U3D 3D Model Import

If your documentation contains engineering drawings, your engineers can save the drawings in Universal 3D (U3D) format. You can then insert the U3D files in browser-based and PDF outputs. Users can then click on the images and rotate them or zoom in and out. (To try it, go to page 173 of the What’s New Guide (http://docs.madcapsoftware.com/FlareV11/FlareWhatsNewGuide.pdf), click on the image in the example, and drag to rotate the image or use your mouse wheel to expand or shrink it.)

Augmented Reality

Finally, the unexpected – augmented reality. Unlike virtual reality, which takes users into a new reality like a game, augmented reality keeps users in this world but adds a functional layer when users view that world on a mobile device. Augmented reality seems to be most commonly thought of in terms of marketing. For example, Starbuck’s Cup Magic has let smartphone users scan specially imprinted cups that invoke an augmented reality layer atop the cup image. The image below, from www.interactivity.la, shows a Christmas cup that, when scanned, displays the singers on the smartphone screen.

Augmented reality goes beyond marketing. For example, the Theodolite app from Hunter Research and Technology (http://hunter.pairsite.com/theodolite/) superimposes compass, GPS, map, rangefinder, inclinometer, and other data onto a scene viewed on an iPhone screen, as shown below:

When would Flare authors use augmented reality? It’s hard to say. The idea is so new to tech comm that it allows functions we may never have thought of. One idea – field service information superimposed over the image of a machine being serviced.


And I haven’t discussed a whole range of other features such as:
  • Customizable keyboard shortcuts, a boon to accelerator key users.
  • Git integration, extending Flare’s version control system support.
  • Advanced page layout control, allowing very complex layouts for print output.
  • An image positioning feature that lets authors control how images fit within text without having to work with float properties in a CSS.
  • A global spelling dictionary that can be shared across multiple projects.
  • Building multiple targets in the background while continuing to work in the foreground.
  • And many more…

Between the extension of existing features and the inclusion of some unexpected new ones, Flare 11 is a major advance. I’m very impressed.

About the Author

Neil is an internationally known consultant, strategist, trainer, and developer for online content in forms ranging from online help to apps. He helps clients design content, select outputs, understand coding, and select and learn authoring tools. To do this, he brings decades of experience in tech comm, with 30 years in a wide range of online formats and tools. (He created the second and third commercial ebooks ever released, for MS-DOS 2.1 and Lotus 1-2-3 2.01 in 1987.) He also spent four years as an industry representative to the WorldWide Web Consortium in the 2000s.

Neil is certified by MadCap Software in Flare and Mimic, and by various other vendors. He is the author of “Advanced Features of MadCap Flare 10” (and earlier versions) and “Creating Mobile Apps Without Coding”, mobile app creation for non-programmers.

Neil writes columns and articles for various professional journals and is a popular speaker at professional conferences. In what passes for his spare time, he builds telescopes, cooks southern barbecue, and is using computer simulators to recreate a lost career as a US Navy fighter pilot. You can contact Neil at nperlin@nperlin.cnc.net or follow him on LinkedIn: https://www.linkedin.com/pub/neil-perlin, on Facebook at facebook.com/neil.perlin.7, and on Twitter at @NeilEric.