Thursday, November 21, 2013

Analytics and Tech Comm - Food for Thought?

This post presents a portion of a LinkedIn conversation thread dealing with using analytics, such as Google Analytics, in tech comm. The thread picks up with my request to the original post. (Thanks to Evin Wilkins for starting this whole thing, and Hagay Vider, Matt Sullivan, and Marion Deland for the responses that form the thread.) And with that...
Neil Perlin
President, Hyper/Word Services
… I'm going to be guest-editing an upcoming issue of the STC Intercom magazine with the theme of the bleeding edge. I've got all my topics covered save for one, the use of analytics with regard to tech comm and online help - RoboHelp, Flare, et al. I'm having trouble finding a writer for that topic but I'd hate to omit it. Hagay and Matt and everyone else - do you guys know of anyone who's familiar with analytics and who's used it in a tech comm context?

Hagay Vider

Technical and Marketing Communications Manager at High Security Labs

Neil, if you're looking for content professionals who use Google Analytics, then you should be looking in a different direction. I have used GA for other purposes, not to get usage statistics of technical documentation, but I understand your reasoning. You should look towards other fields for inspiration.

The most common use of GA is to "monetize" content, meaning that web site owners write content that would grab eyes, which justifies charging money to advertise on their sites. This is different than the Wall Street Journal selling subscriptions, and then restricting some content only to paid subscribers. This is free and open content that's paid for by ads.

Technical documentation is not often monetized, since it's usually provided as a type of "customer service" to customers who already bought the product. The only reason I can think of to perform analytics on technical communications is to coordinate with customer service. Where do customers look for information? What information is missing that causes them to open a service call? Should we include this information in the documentation to prevent service calls?

GA is often used for free sites that provide useful information to readers who will follow through with purchasing a product. Such sites include articles on investing, consumer issues, dieting, health and food. These are often the most popular sites, and advertisers know that their readers are ready to make a purchase. The more hits their pages get, the more money they can charge for ad space. Some of the larger sites have a "contact us" page where they sell ad space directly to customers. They provide analytics results as part of the quote. The smaller sites use Google AdSense some other ad space marketing service.

Another group of sites are "news aggregators". They copy news sites on a wholesale basis, and save the content for subscribers who do research, want to dig up require old content and the like. The analytics helps them know which information is in demand. This is much closer to the requirements of technical documentation.

In any case, using GA on your own technical documentation will not create enough traffic to show substantial analytics. You options are to either publish something and get as many of your friends to visit the site, or you can create analytics on different pages in existing popular site, and show how they compare. Visiting your own site often yourself won't work, since the analytics looks for unique IP addresses.

On to the subject for bleeding edge, technical writers sometimes take jobs writing general interest articles and blogs on technical subjects, like software, consumer electronics, medicine, and the like. Sometimes its very technical. This is actually a rapidly growing area within technical/specialized writing.

I previously wrote articles and blogs for an electronics company. An accountant friend of mine recently asked me to write a blog for his accounting firm's web site. He likes my writing better than his own. A resort where I stayed asked me to write a review. None of these examples wanted to monetize the content, but it's not far. Getting prestige for putting out a blog is usually higher priority for them than the actual analytics, and they probably wouldn't know what to do with those analytics.

The first issue with analytics is why you want it and what you expect to get out of it.

Co-author of Publishing Fundamentals: Unstructured FrameMaker 11. Trainer and Developer in Tech Comm and eLearning

Sorry Neil, I don't know anyone who has done this, but I'd do it on spec for a client if they were interested!

Hagay, I respectfully disagree with your assessment of GA only in terms of monetizing content. While a monetary transaction is certainly *one* goal of GA, knowing more about your users and knowing what they do (and don't) respond to are never a bad idea. Improving customer service and decreasing employee time spent on problem solving affect the bottom line as much as a few more transactions.

And while a small company or resort may not have time to fully contemplate GA on their blog, or even their site, many companies have the scale to do so.

Even small orgs can use GA to determine their spend on marketing, content dev, and other significant activities.

I thought Evan's original premise was a good one, and would bet dollars to doughnuts that embedding the GA code would be do-able, and worthwhile for any org that currently does GA.

President, Hyper/Word Services


Thanks for your post. I don't entirely agree with you regarding tech comm's use of GA since while tech comm (probably) isn't going to be monetizing contact, they still want to know who is using it and its successes and failures (which is basically your point about coordinating with customer service). That disagreement aside, I think your response would make a fine blog post that introduces one aspect of analytics. Do you have a blog on which you could put your post? If not, would you mind if I put it on my blog, with full attribution to you of course, as a discussion point for tech comm?


President, Hyper/Word Services


Thanks for your post in response to Hagay. I think you and I are seeing a different side of GA because we're in the same field, whereas I suspect Hagay is coming at it from a different angle. (Hagay, true?) Watch the April Intercom for an article about analytics for tech comm as part of a bleeding edge theme to the issue.


Technical and Marketing Communications Manager at High Security Labs

Thanks to both of you, Neil and Matt.

Yes, I am coming from a different angle. I have worked with Google Analytics in the past. It was of limited use as a tool for my technical publications, but I more often documented its uses and features in the line of business of the companies where I worked.
The reason GA is so new to technical writers is its limited perceived benefit (I emphasize perceived). GA is not new. It is already very strong in other areas that find its ability to generate revenue or save money. This is also where technical communications can benefit, and benefit the companies who employ the technical writers.

We are already aware how the old school format of technical documentation, which uses the printed page paradigm, is gradually shifting to mostly/only electronic publishing and distribution.

Companies that needed technical documents didn't always see it in full context of its operations and line of business, and neither did the technical writers. What was not so obvious was how technical communications can benefit marketing, sales and support. The technical writers know little about who reads their documentation, how much they actually read (if at all), and especially what content they miss that eventually turns into an expensive service call. This is where the savings comes in - a service call that could have been resolved in advance with a visit to the WebHelp. GA can help locate and link the support expenses to specific items of documented information. I have used GA to a limited extent in my technical documentation, but the traffic was not heavy enough to provide any useful insights.

The newer side is generating revenue through technical communications. I know of companies who are considering monetizing their technical documentation, but none who actually tried to sell it, let alone made any money. This is especially common with companies who market a FREE-MIUM product or service. The initial product is basic and free, but advanced features are only available with a paid subscription or by purchasing the "Pro" version. With this model, users of the basic free product get a short Quick Start tutorial, in a web page, PDF download, Video, interactive Flash, or some combination. The heavier side of technical communications is only provided to paying customers, and is part of the full product support package. Again, I have yet to see a company that succeeded selling its user manuals, but then I am not in contact with every new company.

This is a new area, and certainly "Bleeding Edge."

Co-author of Publishing Fundamentals: Unstructured FrameMaker 11. Trainer and Developer in Tech Comm and eLearning

@Neil, feel free to use this as blog fodder!

I think it's an interesting topic, though as I said I've not implemented GA code in a project yet. If as Hagay said, the sample size is just too small, then perhaps in smaller implementations, it's just not worth it. But even for small samples, you'd get a sense of the number of users, and what they're doing.

at Capensys Ltd.

Coming in on this late...We use Google Analytics to measure our RH projects for clients all the time. We embed the code into the master, and publish as WebHelp We have a different account set up for each client.

It does have limited use - it can't measure exactly who is reading the files, which is fine because it protects the privacy of the user (important in Europe, especially). But it tells the client which city/country the user is in, and whether it is a mobile device. If you dig down, you can see which pages are accessed the most, which is also useful. (While the overall project is addressed as index.htm, the individual pages are bookmarks, and can be found.)

Hope this helps,


Monday, June 10, 2013

Biola.Digital Conference – Observation 1

I gave two presentations about “mobile” at the Biola.Digital ( conference in La Mirada, CA last week. The conference focused in large part on the use of technology in ministry or, per the web site, “…vision, knowledge, and relationships necessary to be thoughtful stewards of digital technologies for the cause of Christ.”

To a degree, the use of technology in ministry has the same issues as in any other setting – ensuring adequate server capacity, building a social media presence, dealing with an audience with different technology skills and equipment, etc. But, as in so many markets, the use of technology in ministry also has its own peculiar problems. One, noted by Jason Caston ( in his presentation “How to Get One Million Social Media Fans”, has to do with the use of social media in a personality-driven environment.
For example, let’s say church X has John Doe as its pastor. (This might just as easily be a conference or company with a specific person as its face.) Pastor Doe has written books, appears in videos on YouTube, and so on. Pastor Doe is the face of the church. For whom does the church solicit followers on social media, Pastor Doe or Church X? It’s important because the departure of Pastor Doe might throw the church into turmoil or kill it outright. The answer appears to be to solicit social media followers on multiple tracks – the personality and the organization. It seems self-evident, but many self-evident things aren’t until after the fact.

Sunday, May 12, 2013

Two Upcoming Presentations about “Mobile” for the Biola Digital 2013 Conference

Do you work for a church or non-profit? Are you near LA? I’ll be giving two presentations about “mobile” for the conference ( run by Biola College in La Mirada on June 4-6.

The conference has three tracks – theology, strategy, and education. I’m speaking in the Strategy track on "Mobile 101: Understanding What Your Ministry Needs to Do Now!" and "A Deep (But Non-Techie) Dive into Mobile."

Why talk about mobile at a conference devoted to ministry?

Technology is everywhere, including churches. The Strategy track presentations reflect this, covering topics like mobile learning, how to get one million social media fans, using Pinterest… and mobile.

How does mobile fit in?

The smartphones and tablets we see all around us are in churches as well, especially those with younger congregations, and there’s more and more talk about needing to “go mobile”. The problem is that just saying “go mobile” is too vague… Without defining what that means, it’s easy to waste time and money and wind up with a disappointing product or no product at all. My two presentations focus on this risk.

Session one, “Mobile 101: Understanding What Your Ministry Needs to Do Now!" introduces the whole subject of mobile. We’ll define:

·         Good (and bad) reasons to go mobile in the first place.

·         Issues to think about when going mobile (such as why your church app isn’t likely to compete with Angry Birds and what this means).

·         Specific ways to go mobile ranging from converting Microsoft Word content to PDF to creating a true “app” for iPhone and Android phone users in your church. (If the latter sounds terrifying, you may be surprised to learn that a new group of authoring tools makes it possible to create an app with little or no programming background at all.)

The second session, "A Deep (But Non-Techie) Dive Into Mobile" picks up where the first session left off. It introduces an iPhone/Android app created for a church outside Boston, MA and shows how to create such apps using tools designed for non-programmers, in this case a tool called ViziApps Studio ( You’ll look at the features in the app, the tool, and modify the app yourself with no programming. The result? A demo app that you can take back to your church to show how it’s possible to go mobile now!

Hope to see you there…

Tuesday, April 2, 2013

My Favorite New Features in MadCap Flare 9

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

Mechanical Features
Synchronization of text highlighting between XML editor and code view

In prior versions of Flare, you might see an issue in a topic that you wanted to fix in code. The problem was that there was no way to find that issue in the code except by eye (“find the first bullet after the second image”) or using the Search feature. Both methods worked but weren’t very convenient.
Flare 9 appears to have solved this problem. Now, you can open the XML editor and code view windows, highlight the desired text in the XML editor, and see the corresponding text highlighted in code view, as shown below.

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

In my experience, most clients’ print outputs are pretty simple. However, an avalanche of new options let you take your print output far beyond simple, such as:
·         Support for crop marks and registration marks in PDF outputs to help your printer determine where to cut the paper and to ensure accurate registration in color printing.

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

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

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

Advanced Expressions in Condition Tags

Flare lets you apply conditions to almost any feature, like creating conditionalized snippets that contain conditionalized variables. You can even apply conditions to conditions, though I’ve never seen anyone do this in a real project.  (If you have done this, please let me know why and how it worked out.)
For all its power, the condition tag feature has a simple basis – include/exclude. If you recall high school algebra, that’s a NOT statement, with an OR statement if you applied multiple tags – e.g. the statement “not ( Primary.HOLD or Primary.Print )” tells Flare to exclude (“not”) any object to which you applied the tags HOLD or Print from the Primary tag set. It’s easy to understand, although it’s easy to get the wrong results if you apply different tags to text, text paragraphs, topics, foldersful of topics, and so on.

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

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

Here, you can use AND, OR, NOT, and () statements to create more powerful but more complex build expressions – e.g. formulas. However, this also adds some new things to watch out for.
·         There are no clickable selection functions other than that Copy From Basic button; you have to type the formula, with the risk of typos. So you have to type carefully and check your entry.

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

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

·         It’s easy to create a complex and powerful build expression that you understand; what happens when you leave? If you don’t document your build expressions, and many people don’t because project documentation is usually something we’ll get to when we have time, your replacement may have a lot of trouble understanding what you did.
Basically, the advanced conditional build tags feature should let you create expressions to cover almost any need but it has to be used with care.

Large Strategic Features

Each of the features in this section is worthy of its own post. Here, I’ll sum up the features and suggest what impact they may have and cover them in more detail in later posts as time permits.
Office 365 Support (Word Import/Output Without Installation of Word)

For years, tech comm is typically done on a local PC. Flare and its projects, Word and its documents, and others – all sit on your C drive. That’s been changing with the spread of server-side version control and Flare’s native support for working on projects on network drives. Yet sometimes you don’t realize that a change is occurring until you reach a tipping point, in my case my discovery that I could put the graphics for a Flare project in the cloud and cut the size of the distributable output by 75%.
In my opinion, support for Office 365 may be that tipping point. Flare 9 users can work in the cloud but remain in the familiar Flare interface rather than having to bolt separate tools and processes together. The support is still in its early stage and the help notes some limits to that support, but this is the first step that I expect to see extended in later versions of Flare, just as Flare 8 introduced HTML5 support and Flare 9 is now extending it. (See below.) If you use Office 365 or are thinking about working in the cloud in general, read about this feature.

HTML5 Enhancements

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

·         Highlighting of search hits.

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

eBooks and ePub3

In my experience, companies are increasingly looking at offering their material in mobile form and Flare has steadily expanded its mobile features since WebHelp Mobile in Flare 6 and ePub in 8. Flare 9 adds more ePub support, including new features, supporting the new ePub3, simplifying the esoteric process of validating ePub output, and adding mobi output for the Kindle.
ePub and mobi don’t support all the features that Flare offers, so you can’t just click a few buttons and get a result with a completely satisfactory design. But the mechanics of conversion to mobile are almost that simple. If you’ve been thinking about moving into mobile, Flare is getting closer to letting you do that for all mobile formats except “true” native apps and without having to buy and learn new software.


Several versions ago, MadCap introduced the Feedback package that let you to create a virtual, Web 2.0 style community of users who could comment about topics in your Flare output, respond to other users’ comments, rate topics for their usefulness, and so on. This “community” existed independently, though you could moderate it (for obvious reasons). Feedback is still supported, but MadCap has now released MadCap Pulse as a new and more powerful version that lets you add a more powerful social layer to your output.
As an analogy, think of Pulse as something like a Flare-centric LinkedIn. It supports commenting, email feeds, communities, questions (like a survey feature), and several that I find to have the most potential - interaction with external systems  like social media sites and helping Flare authors determine what search synonyms, not index synonyms, are required to make searching more useful. Pulse also lets users add to the documentation set by attaching images, movies, additional links and other files, without affecting the documentation set itself. You can also create controlled Communities or Groups in which to set up discussions around specific topics and invite or restrict users to particular Communities or Private Groups.  For more information and a video on Pulse, see


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

Neil has 34 years experience in technical communication, with 28 in training, consulting, and development for various online formats and tools including WinHelp, HTML Help, CE Help, JavaHelp, WebHelp, RoboHelp, ForeHelp, Flare, and many now known only in legend.  Neil is a columnist and frequent speaker for various professional groups and the creator and manager of the Beyond the Bleeding Edge stem at the STC’s annual summit.
Neil is Madcap certified for Flare and Mimic, ViziApps certified for the ViziApps mobile app development platform, and certified in other help authoring tools.  He provides training, consulting, and development for online help and documentation, Flare, Mimic, other help authoring tools, mobile apps, XML, single-sourcing, topic-based and structured authoring, and content strategy through Hyper/Word Services.  He can be reached at,


Tuesday, March 5, 2013

An Overview Look at MadCap Mimic 7

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

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

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

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

·         Distributed via YouTube, making YouTube a free distribution mechanism.
And Mimic is inexpensive, $299 for new or starting from $149 for an upgrade. It’s an inexpensive way to add a visual dimension to online help, training, reference, or marketing materials.

Now for a closer look at Mimic 7.
There are six ways to create a new movie, as shown in the New dialog box below.

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

Once you’ve recorded the slides, you can edit them. Much of that work is on a slide-by-slide basis using the interface shown below.
On the left is a palette of re-usable graphic objects that you can create. On the right is a list of frames in the movie, one way to navigate from frame to frame. The center of the screen is showing slide/frame 18. At the top of the slide is an initial text caption box “Click…” that Mimic added automatically during the recording. You can edit the text in this caption box as needed or just delete it. The red line below the text caption shows the path of the mouse pointer during recording. Viewers won’t see that line; they’ll see the actual mouse pointer move along that path.
In addition to the text caption boxes, you can add highlight boxes in various shapes, audio clips of sound effects or voiceover narration, simulated fields in which viewers can make simulated entries, animation that moves graphics along a trajectory on a slide, and more. Mimic movies can also use conditions and targets, as in Flare, and can be integrated into a Flare project programmatically so that the projects can share conditions, for example, and update automatically.

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

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

However, I consider HTML5 output to be the main reason to upgrade. HTML5 is important if you plan to create movies to run on iOS devices like the iPhone, or be bundled into Flare projects output to Flare’s Windows Mobile output to run on iOS, or run on YouTube. You may not be planning to do any of these in the near future, but check with your management before writing off HTML5 and Mimic 7. Mobile is slowly but steadily pervading the world of tech comm, training, and marketing, and Mimic 7 supports it now, integrated into a familiar interface.
Neil Perlin is a MadCap-certified consultant and trainer for Flare and Mimic. Neil is an independent consultant based outside Boston, MA, operating as Hyper/Word Services (, He is the author of “Essentials of MadCap Mimic 6” (and the forthcoming “Essentials of MadCap Mimic 7”) and “Advanced and Unfamiliar Features in MadCap Flare”, both available at Amazon.