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.
Summary
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
