Friday, December 14, 2018

“RoboCop” and “HLMT” Redux? Don’t Repeat Old Mistakes

If you have any experience in technical communication, you’ve seen, and even made, mistakes. Maybe it was the wrong technology or authoring tool. Maybe it was a project definition that took the wrong path. Such mistakes aren’t surprising; we work in a complex and rapidly changing field.

Many of these mistakes are silly in retrospect. But silly mistakes can also have big repercussions. And the worst thing is to make the same mistake twice. This might seem unlikely but staff turnover erases the “corporate memory”. We don’t learn from our mistakes.

This article describes various mistakes that I’ve been called to consult on, and lessons to be learned from them as we move toward Information 4.0 or whatever the future will be called. Some of the lessons will seem obvious. Others may not be until they’re pointed out.

The mistakes that I describe may make the clients seem incompetent; nothing could be further from the truth. (I would trust the hospital staff to take out my appendix; I just wouldn’t trust them to insert an image into a Word document.) The problem was simply that the clients were moving rapidly into new and usually unfamiliar waters. As they so often are today…

Misunderstanding the Terminology

Some of the most memorable mistakes come from misunderstanding the terminology behind a project. What’s the difference between a “staging server” and a “production server”, for example?

Me: “What browser do you use?”
Client: “What’s a browser?”
Me: “How do you access the company’s intranet?”
Client: “We click that blue “e” icon in Windows. Do you know what that is?”

A forward-thinking client asked me to put some documentation online and move it to an intranet. There were major differences between browsers at that time so it was reasonable to ask what browser they used. The conversation above is almost a word-for-word summary of my discussion with them.

The problem was that the concept of the internet was so new that few people understood the terminology. This was in 1997.

Client: “What is HLMT anyway?”

A client turned to me during a meeting and asked what “HLMT” was. I said I didn’t know. He said he was surprised because it had to do with the web so he assumed I’d know. The light dawned and I said that it was actually “HTML”, the code basis for the web. The client thanked me. This was in 2000.

Client: “Cut and paste? Yes, of course. We use scissors and double-faced tape.”

A client wrote procedure documents in Word, leaving white space for images. They would then copy the images out of medical textbooks, cut them to fit the white space, and paste them in with double-faced tape after printing the documents.

The problem was that the client was interpreting “cut and paste” in everyday terms, rather than in PC terms. (Never mind the innumerable copyright violations.) This was in 2003.

The lesson – Misunderstanding the basic terminology or trying to apply analogies from everyday life like cut and paste wasn’t surprising in the late 1990s. Twenty years later, such misunderstandings still occur because the terminology is still often new and confusing. (“What’s ‘mobile’?”)

All direct and indirect participants in a project have to understand at least the basic terminology in order to avoid talking past each other. Never assume that everybody is speaking the same language.

Misunderstanding the Technology

Equally memorable mistakes come from misunderstanding the technology behind a project.

Client: “WebHelp vs. Web Help”

A company got confused between WebHelp and Web Help. A staffer then wrote an RFP for a WebHelp consultant only to have the approving manager fix what appeared to be an obvious typo and change “WebHelp” to Web Help”.

The problem was that the two formats were totally different. It took several days to figure out what the company was really asking for in order to help them fix the RFP.  (To this day, I always refer to WebHelp as “WebHelp one word” because of that incident.) This was in 1998.

Client: “HTML Help vs. HTML help”

A company got confused over HTML Help vs. HTML help. The company used a help authoring tool called ForeHelp to create the online help project and expected to get the “tri-pane window” in the output. For some reason, it didn’t work. The software vendor’s normally excellent support people couldn’t figure out what the problem was. This went on for ten months.

The problem was that when the author called support and reported the problem creating the tri-pane in HTML “help”, the support reps heard HTML “Help” and asked if the author had compiled. The author didn’t understand what “compiled” meant, assumed that it meant to create the project, and said yes. At that point, the support reps were at a loss. The solution took two mouse clicks, one to compile and one to view the result. This was in 1999.

Client(s): “We’re going mobile!”

A company’s three divisions decided to go mobile but never defined what “mobile” meant. Each division therefore went mobile in a different way, based on its understanding of “mobile”.

The problem was that the term “mobile” is too vague. It could refer to an app, a PDF file, or responsive output from a help authoring tool. And, in fact, the three divisions used those three definitions. This made it impossible to coordinate an enterprise-wide mobile effort and caused political problems because no division wanted to abandon its effort in favor of another division’s. This was in 2017.

The lesson – Misunderstanding the technology, like misunderstanding the terminology, wasn’t unusual in the late 1990s when everything was new and confusing. Companies often failed to recognize how confusing the technologies could be. The same holds true today, just for different technologies. (What’s a “bot”?) But misunderstanding the technology can lead to buying the wrong authoring tools, buying the right tools and using them the wrong way, hiring the wrong writers, or all three.

All direct and indirect participants in a project have to understand at least the basics of the technology in order to avoid talking past each other. Never assume that everybody is speaking the same language. (It’s a good idea to hold some education sessions for all the participants. Some will get annoyed at what seems like a waste of time, but I tell clients that it’s better to have people mildly annoyed at an apparent waste of time than to have them really annoyed when the project goes awry.)

Misunderstanding the Workflow

Misunderstanding the terminology and technologies can lead to inefficient or just bad workflows.

Client: “Cut and paste? Yes, of course. We use scissors and double-faced tape.”

The same issue as described earlier.

The problem was that the misunderstanding of the terminology lead the client to create an incredibly inefficient workflow. Again, this was in 2003.

Client: “We use "authoring tool X". We were never trained on it so we use instructions that were written by a former member of the doc group.”

This is common.

The problem is that the workflow may have changed since the original author wrote the instructions. The tool probably has. And the original author may have made mistakes in the instructions that have been passed on between generations of authors. The result is that the project’s foundation is becoming increasingly unstable. This was in any year ranging from 1995 to today.

Client: “We create online and print outputs from our help authoring tool so we create two stylesheets, one for the online and one for the print.”

This is also common.

The problem is that the authoring tool may have features that can streamline this workflow such as the ability to create one stylesheet with two mediums, one for online and one for print. But the writers must be familiar with the tool or trained on it to know that these features exist. This was in any year ranging from 1995 to today.

Client: “We were wondering what those ‘styles’ things were.”

Writers for a real estate company used Word to write their company’s procedure manual, each writing a different section. The writers didn’t use styles. Instead, they did local formatting. They were sharp enough to realize the need for consistency and developed a set of formatting standards.

The problem was that they invariably deviated from those standards. When it was time to combine each writer’s output to create the final manual, they had an enormous amount of cleanup to do to make the formatting consistent. This was in 2011.

The lesson – Misunderstanding terminology or tool features often leads to inefficient or just plain wrong workflows that require work-arounds. In the past we had the time to fix the problems or do the work-arounds, often by hand, because the time-to-market requirements for our documentation were looser than they are today. Today, as content becomes increasingly important to your company, making the workflow efficient and effective is becoming crucial.

Justification to Management

Mistakes in justifying buying new software and training employees to use it can be harmless, or they can lead a company down the wrong path.

Client: “My daughter came home from college and said ‘Dad! The company has to start creating online help!’ and I said ‘Okay!’”

A manufacturing company division manager put his division on the road to online documentation based on that statement from his daughter who was home from college. There was so little guidance in the old days that the manager could tell his IT manager (tellingly, not the documentation manager) to buy whatever tool seemed appropriate, with no needs assessment or tool evaluation. That was justification to management in a simpler era, 1996.

Client: “We have an HTML tool that we adopted in 1999 and it seems to be working fine except for a few minor problems.”

A federal agency had gone online in 1999 and found the experience so difficult that they didn’t want to repeat it. But the old tool was no longer supported and no longer followed modern coding practice – it was a dead end. The only solution was to buy a modern authoring tool and convert thousands of pages from the old HTML-ish format to XHTML. It was going to be a very tough job but management didn’t want to change, instead telling the writers to create work-arounds to the problems. That was in 2015.

The lesson – Justifying the cost of a new technology or tool was easy when documentation wasn’t taken seriously. But documentation/content today must increasingly fit into corporate environments and support corporate business and strategic goals (not technical communication goals), has become more complex and expensive, and must compete with other ideas being presented to management. Proponents need to present and defend it on the business grounds of how it benefits the company. Any other approach is likely to fail.

General Silliness

I’ll end with two mistakes that suggest just how easy it is to go wrong.

Client: “We want to use Doctor Help but we can’t find it.”

I gave a presentation to the Boston chapter of the STC (Society for Technical Communication) in 1993. In that presentation, I mentioned various help authoring tools including Doc-to-Help. An attendee called me a week later to ask where she could find “Doctor Help”. I told her I’d never heard of it. She said that I had specifically mentioned it in the presentation. We eventually realized that when she heard me say “Doc-to-Help”, she assumed that I was speaking in a Boston accent (the “r” at the end of a word is often ignored so that “park the car” comes out as “pahk the cah”) and meant “Doctor Help”. But her company wasted several days looking for “Doctor Help”.

And finally…

Client: “We want to use RoboCop!”

A division of a manufacturing company used “Lotus Notes” to put its documentation online. During a visit to another division, the manager saw their online documentation, liked its format better than what Notes could create, asked how they created it, and was told “We use Robo-something.” He told his IT manager to switch their online documentation from “Notes” to “RoboCop”. The IT manager spent a month searching for it before finally stumbling over “RoboHelp”. This was in 1995.

The lesson – Some mistakes are just so odd and silly that they’re hard to defend against. But they suggest that you check your basic assumptions carefully when you start a project and re-check them over the duration of the project in the face of changing technologies.


It’s easy to summarize this article. Companies are continually moving into new, confusing, and rapidly-changing areas that lie outside their core competencies. Because of this, it would be surprising if a company did not make mistakes. But as the complexity of the technology goes up and time-to-market goes down, the cost of mistakes goes up as well. So while we’ll never avoid making mistakes, we can at least try not to repeat the mistakes of the past.

A version of this article was originally published in ISTC Communicator, Winter 2018