One of the technical writers on my team found a pretty cool T-shirt online. The silkscreen on it said:
“I’m a technical writer. I solve problems you don’t know you have, in ways you can’t understand.”
Maybe that’s just a bit over the top…but it does make a point. As the client you aren’t expected to know the details of what’s wrong with your documentation. And we don’t expect you to know how to make it right. What we do hope is that you’ll recognize that our skill set can add value to one of your more valuable assets: your documents.
I’ve written about several ways that technical writers add value—writing, editing, graphics, etc.—but before any of those activities start, you need to have standards in place. How do you know if you’re doing it right, if you haven’t defined what “doing it right” means? So the step of developing standards is important, and as technical writers we need the client to “buy-in” to their importance. That’s the first step. After that the challenge is to get everyone on-board to comply with those standards.
But let’s step back for a moment and make sure we understand what we’re talking about here. The standards I’m talking about are more than just the basics rules of grammar, punctuation and format found in an off-the-shelf style guide. Style guides like the Chicago Manual of Style, the Canadian Style, or others (there are lots to choose from) are important. But I’m talking about going beyond that to develop a set of rules for your situation. For example, rules about word choices that will be understandable in your industry, on your site, and to your workers or customers.
Are your documents used by the general public? Are they in-house procedures for engineers? Are they operating manuals/procedures for plant personnel? As usual, the bottom line is always the user. Will the documents consistently “connect” with the people who will use them?
There are a lot of decisions that go into creating a set of standards for a client. We start with an analysis of the user, including who they are, what the content is about, and what the documents will be used for. We investigate what is unique about the content. Does this industry use specialized jargon? Is that jargon widely accepted? Are there good reasons to maintain local preferences, or should we try to have the user change to more widely accepted standards? Sometimes compromise (on both sides) is necessary.
As an example, take one of my recent clients—a large mining company. This mine and mill has been operating for almost fifty years and much of their operational language has evolved over that time. They like to use terminology that makes a typical technical writer cringe. For example, “Brine up the plant,” means start a series of pumps and open the correct valves to get brine flowing through multiple stages of pipes, tanks and other equipment. “Start the flakebreakers,” “Start the roll mills,” or “Start the Gundlach,” could conceivably all refer to the same piece of equipment. “Press the on button on the ABC page of the Foxboro screen,” is understandable to operators who have worked there for years, but it breaks most of the conventional style rules (according to the Microsoft Manual of Style).
Sometimes brand names become synonymous with a process or type of equipment. “Start the Bird,” refers to a common brand of centrifuge, except “Bird” was bought out a few years ago by another company that no longer uses that name. In documentation do we continue using the common term (Bird), change to the new manufacturer’s name (Andritz), or use the generic term? And how difficult will it be to convince personnel to make that change?
Given the task of updating and creating new documentation, the technical writer has to navigate the delicate path of establishing new standards, and then get the client to cooperate. This can be challenging. Often, this can involve changing years of ingrained habits. We’re back to the idea of “buy-in”.
When a client makes the decision to upgrade, or create new documents, and they see the need for expert help with the task, they have to also decide whether to accept a re-evaluation of their standards. Experienced technical writers will work with their clients to develop a set of standards that will strengthen their documentation. That might involve some adaptation (maybe even some inconvenience and discomfort), but the change will make their documents more consistent, which will decrease the chance of ambiguity. Ultimately, that will result in better productivity, quality and safety. Isn’t that what we all want?
Sphere: Related Content