Last week, Alan J. Porter published a very interesting blog post about making assumptions. One key lesson that jumped out at me in that post is that having consistent terminology, and using that terminology consistently, is crucial. Not just to support but for technical communicators as well.
Terminology that isn’t consistent, and which isn’t used consistently, can cause more than just a little confusion. And documentation that doesn’t use that terminology consistently can cause more problems than it clears up. Not only with customers, but within your company and project as well.
Let’s take a look at this …
A couple of examples, past and present
Back when I was working for The Company That Shall Not Be Named, I was documenting a supply chain management application. Another project started up, which used elements of the code from the software that I was working on. Another member of the technical writing team was assigned to that project, and one day he sent me an email asking how a certain module behaved. I replied that I didn’t know; said module didn’t exist in the application that I was working on.
He sent me an email, pretty much going ballistic on me. After I (rather harshly) told the other writer to calm down, I asked him to explain what the module in question did. When I read the explanation, I realized that, yes, the module did exist in what I was documenting. But it was named something entirely different. Named so differently, in fact, as to be unrecognizable.
For the second example, let’s jump forward to 2011. Last month, to be precise. In my current gig, one of the several projects that I’m juggling had a document called a tip sheet mentioned in a firm-wide communication. But when I looked at the documents for that project (both current and previous versions), I couldn’t find that tip sheet anywhere. I started to get worried that something had been missed or lost.
It turns out that the internal client had called the document a tip sheet. The actual name for that type of document within the company is a job aid. For a while there, I and the rest of the project team were confused. And we were worried that we’d have to add time to develop an extra document to a project that was on the verge of wrapping up.
Implications
Obviously, one major implication is confusion, both among the members of the project team with which you’re working and your users. If you tell someone to look for a quick reference instead of a user guide, they’ll get the impression that a document is missing. That calls into question the completeness and accuracy of the documentation set.
Going back to the example from The Company That Shall Not Be Named, not consistently naming GUI elements or functions in an application can mess up any attempts you might be making at reusing content. Especially if those GUI elements or functions are used across several applications.
Neither case (and I’m sure there are more cases) is pleasant, but they can be avoided.
Getting around the problem
The best thing to do in this sort of situation is to do an audit of both the documentation that you’re writing, and the applications that you’re documenting. Put everything — titles, names of GUI elements and functions, and anything else that you can think of — into a spreadsheet. Then, compare all that information to isolate the inconsistencies.
This takes time and effort, and you’ll need to enlist the help of various SMEs to do the job properly. The time and effort are worth expending. In the end, you’ll be able to improve consistency across the board and decrease any confusion — both internally and with clients.
Thoughts? As always, comments are welcome.
Photo credit: Camabs from Photoxpress