Wednesday, November 19, 2014

“Float” – CSS Feature and Symbol of Change

Ever since I started the Bleeding Edge session at the Society for Technical Communication Summit in 1999, I’m asked how quickly something new really emerges to affect technical communication. It doesn’t happen that often but it does happen – Microsoft’s introduction of HTML Help at the WinWriters conference in 1997 turned online help in a new direction in an hour. This column discusses another such example of change, the CSS “float” property. The float property’s impact won’t be as quick or dramatic as that of HTML Help but I think that what it symbolizes for tech comm is just as far-reaching.

The W3C introduced float in CSS1 in 1996. (See But it remained little known in technical communication until responsive design, promulgated in 2010, came to tech comm through help authoring tools in early 2014. In this column, I’ll briefly describe the float property’s function before turning to the larger issue of what I think it symbolizes for technical communication.

What’s “Float”

Float is a CSS property that lets us position elements on HTML pages. No big deal, you say. We’ve done that for years using simple inserts. True. What if we need multiple graphics side-by-side on a page? Again, no big deal. Create a table, hide its row and cell borders, and insert the graphics in adjacent cells in a row. Philosophically, using tables for page composition is wrong but it’s worked fine for years. Until responsive design arrived.

Responsive design lets us create one (the crucial word) online output that automatically reformats itself for the device on which it’s displayed. For example, say you have to create online help to run on large-screen devices like desktops and laptops and small screen devices like smartphones. You can create two outputs, each designed for its target device. But now add support for 10” tablets? That’s three outputs. Then 7” tablets? That’s four outputs. At some point, you won’t have enough resources to create and maintain all your different outputs. Responsive design solves this problem.

Responsive design lets you create one output that can detect the properties of the device on which it’s displayed and tailor itself accordingly. For example, three graphics laid out horizontally when displayed on a large screen automatically shift to a vertical format as the screen gets narrower. On the first screen below, I inserted the first group of three graphics in a table. I inserted each graphic in the second group normally – not in a table – but specified a left float for it. On a wide screen, there’s no difference.

As the screen narrows however, like shrinking to tablet size, the graphics in the table can’t shift because the table controls the layout. The result is the horizontal scroll bar. But the graphics in the second group, controlled by the float setting, automatically start shifting to a vertical format shown in the next image.

As the screen narrows further, to smartphone screen size, the graphics in the table still can’t shift but the second set of graphics, controlled by the float setting, automatically shift to a full vertical format as shown below.

Float also lets us move whole columns, change how text aligns next to images, and more. This is what lets us create the “fluid grids” that give responsive design much of its layout flexibility.

The float property can get very complex but it’s easy to understand and apply for most online help and documentation projects. For example, to get the graphics to behave as shown in the figures above, the code is simply this:

Your help authoring tool’s stylesheet editor lets you add the floats without getting into the actual code. You can start experimenting with it now.

What’s the Symbolic Importance of the “Float” Property?

Why spend an entire column on a little-known piece of CSS code? In my opinion, float symbolizes four shifts taking place within technical communication.

·         Online superseding print – If you only output print, float is irrelevant. But if you output print and online or online only, you should optimize your content for online. Some techniques for doing so have been available to technical communicators for years, like using relative size units (em, rem, or %) for text rather than the familiar points, or embedding index entries. Float is the latest such technique to reach us. The more you think “online” first, the more in tune you’ll be with changes in technical communication.

·         Growing interest in output to mobile – For years, computer screens were so large that we rarely had to worry about screen real estate. But growing interest in mobile as a single source output option makes it increasingly important to find automated ways to use the same content on different-sized screens. Programmatically-controlled layout modification techniques like float do that and let us adapt quickly as new output requirements appear.

·         HTML5 output – HTML5 output itself doesn’t need floated graphics. But one of HTML5’s benefits is responsive design, and you’ll want to look at using float to make the most effective use of responsive design.

·         Increased development rigor – Poor development practices like HTML tags with no end tags and tables created by using the tab key to create columns have largely vanished as our authoring tools and practices improved. Others, like local/inline formatting, are slowly vanishing as more authors use styles. The result is that improvements in programming practices are reaching increasingly esoteric areas like graphic positioning control. We’ll never totally eliminate bad practices and “hacks” but we’ll minimize them through techniques like float.


The symbolic effect of float is that it illustrates how web coding practices are increasingly available to the technical communication world. As technical communication moves away from “writing” and toward “content” and the lines between web development and technical communication continue to blur, techniques like “float” push technical communicators closer to web developers, letting us future-proof our material and our jobs and get into increasingly interesting work.

About the Author

Neil is president of Hyper/Word Services ( of Tewksbury, MA.  He has 35 years of experience in technical writing, with 29 in training, consulting, and developing for online formats and tools including WinHelp, HTML Help, JavaHelp, CE Help, XML, RoboHelp, Flare, and others now almost unknown.  Neil is MadCap-certified for Flare and Mimic, Adobe-certified for RoboHelp, and Viziapps-certified for the ViziApps mobile app development platform. He is an STC Fellow and the founder and manager of the Beyond the Bleeding Edge stem at the STC summit.  You can reach him at

Thanks to Allen Beebe, Cheryl Landes, and Deborah Sauer for their comments.

This post first appeared in the Society for Technical Communication's Intercom magazine (

Tuesday, October 14, 2014

Book On Responsive Design

Per my presentation on responsive design at Lavacon on Monday, here are two books that I'd immediately recommend on responsive design and CSS.

- "Implementing Responsive Design" by Tim Kadlec, New Riders. Written more for programmers than help authors, but I'd recommend this book for the people at the presentation who were looking to go beyond what a help authoring tool can do through the GUI.

"The CSS Pocket Guide" by Chris Casciano, Peachpit Press. A easily digestible summary of the depths of the Cascading Style Sheet standard.

Sunday, July 20, 2014

Questions From My July 18 STC Webinar on CSS

Mary C: Does RoboHelp provide a basic CSS that one can adapt?
Yes. When you create a new RH project, RH automatically creates a basic CSS called default.css. You can use this CSS and modify its properties, or (my suggestion) copy it, save the copy with a name that ties it to the project or (better) your company (in order to be able to apply it to multiple projects), and modify its properties.

Ellen C: Is it possible to create unnumbered items in a numbered list in Word?
Yes, but there doesn’t seem to be a way to do that the way you would in HTML and CSS (or else I couldn’t find it). To do so manually, press Shift/Enter after a numbered item to add an unnumbered paragraph that keeps the indent and doesn’t change the sequence of the next number. Keep pressing Shift/Enter to add more unnumbered paragraphs. When you finish, press Enter to go back to regular numbering style.

David M: What application do you recommend to create a CSS?
It depends. Do you want to create a CSS for a project done in an authoring tool or do you want to create a CSS independently of any project or tool? Email me at to let me know and we can discuss from there.

Suzanne S: I'm currently using RH10 and we will be upgrading to RH11 for responsive design. Fonts and margins are currently defined in point sizes. To make the output work, do we need to make modifications to the style sheet to use relative size units?
The more you use relative size units the better the responsive design will be.

Barbara: I took over a project with many tags with the style within each tag. I have changed this by adding classes like p class=BodyText" and so on. Is this not correct?
You’re correct. The fewer the sub-classes the better, but you definitely want to replace inline formatting with sub-classes.

Wednesday, June 11, 2014

Author! Author! With Flare

Ever wanted to write a book that people can buy on Amazon? Perhaps a technical book, perhaps a book of family history, or anything in between.

In this post, I’ll discuss how to do that using MadCap Flare as part of a larger tool kit that lets you publish a book to Amazon in both print and ebook format at mind-bogging speed.

By way of background, I’ve written seven books in my career. The “Small Business Guide to Computers & Office Automation: A Comprehensive Overview of Computers and Modern Office Technology, and How to Select a System”, was published in 1985 by Knowledge Industry Publications. The second, an update of the office automation book, was published by an in-house press in 1989. The original book took about five months to write and almost as long to publish. The slow publication process made it hard to write a technical book because it was almost impossible to update the book once it entered the process even though the subject matter itself might be changing. And so I stopped writing commercial books.

Then, in 2010, two things happened.

First, the late Nan Fritz, president of nSight, a consulting company in Burlington, MA, said “Neil, you’re a consultant. You have to write a book.”  I decided she was right and, after some thought, decided to take a MadCap Mimic course that I’d written several years earlier and repurpose it in book form. That meant that most of the writing was already done, in Word format.

Second, I found a blog post, now lost, that discussed why consultants should write books and why and how to self-publish. The gist of that post was that while it was prestigious to have a “real” publisher, the process was slow, publishers paid low commissions and no advance, and provided minimal marketing support. Self-publishing and “print on demand” technology made it possible to write a book and make it available on Amazon quickly and inexpensively but with a higher commission rate. There was still no advance and you were on your own for marketing, but that was like working through a real publisher anyway.

So I tried it. In the process, I put together a tool kit and workflow that I’ve used to write five books since 2011, all available on Amazon (blatant sales pitch warning). The books are “Essentials of MadCap Mimic 6”, “ Advanced and Unfamiliar Features in MadCap Flare 8”, “Advanced and Unfamiliar Features in MadCap Flare 9”, “Advanced Features in MadCap Flare 10”, and “Creating Mobile Apps Without Coding”. In the rest of this post, I’ll explain the tools, the workflow, and point out some lessons learned.

The Tools

The tool kit consists of:

·         ·         Flare ( to write the content.

·         Amazon CreateSpace ( to convert the Flare output into a print book and put it up on Amazon.

·         Amazon Kindle Direct Publishing (, also known as KDP, to convert CreateSpace’s print output to Kindle format and put it up on Amazon.

The Workflow - Flare

The most efficient writing workflow was to treat the book like any Flare project. I also planned from the start to write multiple books using the same basic Flare settings, so I initially set up the page layout, CSS, and one table CSS for the Mimic book with a view toward reusing them.

·         I set up the page layout using a custom size (6”x9”) and default 1” margins. (I used Flare’s 6”x9” because that was the CreateSpace size that I planned to use for the printed book and matching the sizes from the start meant fewer reformatting problems when publishing.) I added the book name in the header block and the “page n of N” page numbering template in the footer and that was that for the page layout. I could now re-use the page layout in multiple books by copying the flpgl file from project to project and simply changing the book name in the header.

·         I set up a simple CSS, specifying h1, h2, h3, p (paragraph), Note, Tip, and Caution styles. I made all the settings in the default medium, then switched to and used the print medium. (Why not make all the settings directly in the print medium, since that was the medium I was going to use anyway? Most of my Flare work involves online outputs using the default medium and if I used the print medium as the “default” for the books, there was a risk of getting confused between mediums. Not as efficient an approach as simply designating the print medium as the default but with less risk of confusion.)

·         I set up a very simple, black and white-oriented table CSS to ensure simple printing.

For each new book then, the overall workflow was this:

1.       Create the new project in Flare with MS Word as the primary target. (All the file conversions to print and Kindle take place in CreateSpace and KDP, not Flare.)

2.       Created the outline in Flare, with each section in the outline being a topic.

3.       Imported the page layout, stylesheet, and table stylesheet, making sure to change the heading in the page layout to the new book title. (I forgot to do that once and wound up generating a proof (final review) copy of the Flare 8 book that was perfect except that it used the Mimic title in the heading. A silly mistake but easy to fix.)

4.       Created a target called “ Word” and made it the primary target.

5.       On the XML Editor toolbar, set the Layout and Medium options to Print. (This may sound like a lot of work so far, but most of it was one-time for the first book. I could then copy those files to the new book project. The book-specific work took minutes.) I then started writing.

Several things to be aware of as you write:

·         Bullets work fine in the print output generated by CreateSpace but not in the Kindle output generated by KDP. This is a problem if you’re writing a technical book because bullets are so common. You’ll have to find a workaround, such as changing your wording or indenting “bulleted” paragraphs.

·         Watch your word spacing. In several cases, Flare inserted two spaces before a word but only showed one space until I saw the Word output.

·         MadCap Capture works well for capturing screens and inserting them in topics. (You can use any screen capture tool. However, don’t draw highlight boxes on screen shots because the area within the highlight box will become opaque in CreateSpace.)

·         Set the h1 style’s page-break-before property (in the PrintSupport group on the Stylesheet editor) to Always to avoid having a main heading at the bottom of a page and the text on the next page. However, if you have two short topics that both start with h1, you can wind up with two facing pages that are mostly empty and have to close up those two headings in Word.

·         Rewrite your material to avoid having a paragraph that ends with a short line that runs onto the succeeding page. If this happens, you may wind up with a left-facing page that contains a single word and the next topic starting on the right-facing page. This is fine but looks odd.

The table of contents can take some finagling depending on the structure you want. There are too many options to cover in one blog post, so I’ll put out an open offer to answer any questions down the road.

When you’re done, generate the Word output. Two things to watch out for when you do:

·         On the Advanced tab of the Target editor in Flare 10, select Generate TOC Proxy and Generate Index Proxy in the Output Options group. (You can also select Generate Glossary Proxy if you created glossary entries.) If you have an older version of Flare, you can generate the TOC and Index but you’ll have to do so using special-purpose topics. See the help or my Advanced Features… book.

·         On the Advanced tab of the Target editor in Flare 10 or before, select the Embed Images in Output option in the MS Word Output options group.

You can now review the Word file to make sure everything is right. If you need to change the content, you can make the change in Flare and re-generate the Word output or make the change in the Word output and separately in Flare. Also check for bad page formatting, such as having one line in the last paragraph of a topic on a separate left-facing page. When you’re satisfied, you’re done with Flare and ready to move into CreateSpace.

The Workflow – CreateSpace

CreateSpace is a book production, pricing, and distribution tool. It lets you set up your print book’s page size, color, and cover, plus distribution and pricing options for various Amazon channels. The process is step-by-step and you can perform all these tasks for free or pay for professional support. I did it myself and, while the results might have been better if I used the support, I thought they were good enough. (Part of the decision between do-it-yourself versus using a designer is the choice between time-to-market and aesthetics.)

When you finish laying out the book, including checking the layout in a page simulator, you can check a virtual copy or a printed proof copy. I recommend using the printed proof for two reasons. First, there’s just different feel between holding something tangible versus virtual. Second, you’ll want to see how your images look. (My main problem has been that the pixel density of my images is lower than CreateSpace prefers. CreateSpace will complain but let you ignore the problem. By getting the printed proof copy, I can make sure that the images really are okay.) Once you’re done, you submit the book for final review by CreateSpace.

After you fix or ignore any problems that CreateSpace identified, you give CreateSpace the go-ahead to put the book up on Amazon. CreateSpace will then slide you into KDP.

The Workflow – KDP

KDP is the ebook side of CreateSpace. KDP will take the files from the CreateSpace work and use them for the Kindle output. The process is almost effortless.

Two Obvious Questions

The first question is how long the whole process will take.

The writing part, in Flare, is up to you. Depending on how well you know the material, you might write the book in six months or, as I did for the Flare 10 book update, about a month.

The real time saving is on the publishing side with CreateSpace and KDP. The first time I did this, for the Mimic book, I worked slowly and thoroughly and the entire process took eight hours! (As opposed to nearly five months.) My book was on Amazon in print form and Kindle form the next day. As spectacular as I thought this was at the time, the publishing process for my latest book, “Advanced Features in MadCap Flare 10”, took an hour and a half! I ran through the process in the morning, the print version was on Amazon that afternoon, and the Kindle version the next morning.

This speed has totally changed how I write books. I can now write a book and time it for release with the software it’s describing without having to factor in months of lost time for production.

The second question is why not write the book directly in Word rather than write in Flare and output to Word? There are two answers. First, I’m a MadCap certified Flare trainer and consultant, so it made sense for me to explore what Flare can do. More relevant is the fact that Flare’s control files, especially the CSS, table CSS, and page layout, provide a rigorous but almost invisible degree of control as I write. For example, by making the CSS the master CSS for the project, my content formatting takes place automatically. Basically, it’s a snap to set up the infrastructure of a new book, with better control than Word and without the quirks.


Writing a book will never be easy. But using Flare in conjunction with CreateSpace and KDP means that the writing phase is better controlled and the publishing phase is so quick as to be almost irrelevant in your planning. Try it. You’ll like it. I did.

Wednesday, February 5, 2014

Adobe RoboHelp 11 – A Review

RoboHelp was one of the first HATs (help authoring tools) and has long had a big part in molding today’s online help and content world. Adobe acquired RoboHelp in 2005 as part of its purchase of Macromedia and has been extending it since then, starting with v. 6 in 2007 and continuing through v. 11, released on January 14, 2014.

In this review, I’ll focus on what I consider to be the most significant features of RoboHelp 11 and what they say about trends in tech comm. There are two, enhanced support for responsive design as part of HTML5 publishing, and the cloud-based collaboration added to the Resource Manager.

HTML5 Publishing and Responsive Design

I’ll start with a quick overview of HTML5 and responsive design if you’re not familiar with the terms.

HTML5 Concepts

HTML5 is the successor to XML and earlier versions of HTML. It’s both a coding language and an output format. RoboHelp 11 still uses XHTML, introduced in v. 8, as the native coding environment, but added HTML5 as a browser-based output format in v. 10 and extended it in v. 11. You can still use WebHelp for browser-based outputs, but HTML5 has several benefits that make it worth looking at as a replacement for WebHelp, including:

·        Searchability by web crawlers. The WebHelp output format has met our needs for years but has a problem that didn’t manifest itself until web search crawlers came into use. WebHelp uses “framesets” to controls layout, but framesets block web crawlers from going beyond the home page in browser-based help. The result is that the online help that you write and distribute as WebHelp won’t be found by a crawler and won’t appear in the list of hits from a Google search. In other words, users can’t find your content through Google. This may not matter if the content is behind a firewall or login and only available to customers. But if your company is adopting a more public-facing strategy, this can be a strategic limitation. HTML5 fixes that limitation.

·        Support for CSS3. This extension of the CSS (Cascading Style Sheet) 2 standard gives more power and flexibility for formatting under modern browsers.

·        Support for a new type of mobile apps called “hybrid apps” that are based, in part, on HTML5. RoboHelp doesn’t output hybrid apps, but the HTML5 code that it does output forms part of the foundation for those apps. In other words, HTML5 output is a step toward hybrid apps.

Responsive Design Concepts

The idea for responsive design arose as more and more devices with different screen sizes, resolutions, and other properties appeared on the market. We can optimize our outputs for one or two devices, but it quickly becomes technically difficult and cost-prohibitive to optimize our outputs for every device on which they might appear. The emerging answer is “responsive design”.

Responsive design says that content can automatically change its design based on the properties of the device on which it’s displayed – e.g. it’s device-agnostic. For example, HTML5 output from a project can change its design depending on whether it’s displayed on a PC, tablet, or smartphone. (The image below shows how content might reformat itself based on the device. The three images look the same at first glance, but note how the Greek temple, the Adobe icon, and the controls move or disappear depending on the output. Automatically…)

RoboHelp’s Support for HTML5 Output and Responsive Design

RoboHelp 10 supported what Adobe called “Multiscreen HTML5” – basically responsive design. It used “screen profiles” (to specify different screen resolutions that controlled the redesign), “screen layouts” (to design the page types and customize them for the different resolutions, and CSS “media queries” (to define the specifics of the page format for each resolution set through the screen profiles). This mix of features let you automatically change the design of the output and, by using conditional build tags, change the content itself depending on the device. It was a good start, but there were two issues.

·        Some of the concepts, particularly CSS media queries, were new to many users.

·        Some of the work, especially screen layout design, was complex and could be time-consuming.

RoboHelp 11 goes a long way toward addressing both issues by adding a new output type, Responsive HTML5. Responsive HTML5 is a streamlined version of Multiscreen HTML5 that uses predefined layouts for different screen sizes and properties. In other words, much of the setup work has been done for you. If you do want to customize a layout, the process is semi-wizard-driven. To contrast the two approaches, the image below shows the layout editor for the Topic page type in Multiscreen HTML5.

There’s a lot of power available in the toolbar but you have to know what you’re doing. In contrast, the image below shows the layout customization editor for a layout, in this case the Theme2_Government layout, for the Responsive HTML5.

The many screens prompts make it easy to see what screen object you’re changing and the options are clearly labeled in the Properties pane. So customization will be fairly straightforward, hopefully tasteful as well. And Adobe has a link to a layout gallery which currently lists two predefined themes, with more sure to come, so you won’t have to start creating yours from scratch.

So Responsive HTML5 is easier than Multiscreen HTML5 but less customizable. The main difference is that Multiscreen HTML5 lets you use conditional build tags to vary the content for individual devices while Responsive HTML5 lets you use conditional build tags but applies the same build tagged content for all devices. This should be a minor point if you want to output the same content to all devices, but may affect your planning if you literally want different content output to a tablet versus a smartphone.

If all this sounds confusing, here’s a simple summary. If you want to output a project using responsive design, open the project in RoboHelp 11, select Responsive HTML5 output in the Single Source Layouts pod, select the desired layout on the General tab, and generate. When RoboHelp finishes generating, click the View Result button (and allow blocked content if you use IE). The output displays in a browser window. Now grab a corner of the browser window and start reducing its size. Once you get to certain sizes – think tablet and smartphone – you’ll see the format change automatically. You’ll have to think about the actual design but the sheer mechanics are impressively simple. And it’s just neat to watch.

Cloud-Based Collaboration via Resource Manager

I’ll start off with a quick overview of the Resource Manager if you’re not familiar with this feature.

Adobe added the Resource Manager several versions ago as a way to share files between projects. For example, let’s say you want to use the same CSS in two projects. The old approach was to find the desired file in the “master” project’s folder in Windows Explorer and copy it to the other project. This worked, but you were doing the file “sharing” manually, outside RoboHelp, so it was easy to paste the copy of the file-to-be-shared in the wrong folder.

The Resource Manager eliminates this problem. You’re sharing the files in RoboHelp under RoboHelp’s control, so they’ll automatically be put in the correct folder. 

The one thing missing in this scenario was file sharing via the cloud. RoboHelp 11 fixes this by letting you set up a shared location using various popular cloud-based services rather than a network drive. You’ll see this option in the Location Type field on the Add Shared Location dialog box that displays when you click on the Add Shared Location icon on the Resource Manager pane, shown in the image below.

You can select from Dropbox, Google Drive, SkyDrive, or others that you might use. When you select one, RoboHelp will find its folder on your PC and fill in the Path field for you. You can also set up subfolders within a service and select just that subfolder. Once set up, you can share topics (new in v. 11 – previous versions didn’t let you share topics) and various control files. If a topic contains embedded elements such as images, RoboHelp will detect their use and carry them over with the topic. (You will have to pull in any snippets separately, but RoboHelp will add them to the topic once you do.) There are also various ways to synchronize changed files.

Overall, the cloud-based collaboration feature is a useful extension of the file sharing concept behind the Resource Manager and a reflection of changes in tech comm.

Other Changes

In addition to the two main features defined above, several others correct problems or omissions. These include:

·        Importing headers and footers when importing a Word document.

·        Defining different headers and footers in different master pages and applying them to different page types in print output.

·        A new color scheme for the interface for greater contrast and readability.

·        SWFs now display and play when included in Word output.


RoboHelp 11 will be largely familiar and easy to learn for any user of an older version. The biggest new convenience is the addition of cloud-based collaboration, but even that fits into Resource Manager.

The most important new feature, in my opinion, is the addition of the Responsive HTML5 output. Few of my RoboHelp clients need mobile or display-agnosticism yet but every one I’ve spoken with sees it as on the horizon. Responsive HTML5 makes it easy for them to get their feet wet in mobile and should help them ease into the full power of the Multiscreen HTML5 output.

Do you need to upgrade to v. 11? If you don’t need responsive design, cloud-based collaboration, or multiple headers and footers in your print output, probably not. But if mobile or display-agnosticism is on your horizon, RoboHelp 11 is a worthwhile upgrade and a job well-done by Adobe.







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.