Spell check

Steven was an engineer at a US-based company whose leadership had decided to take some dramatic cost-saving measures. A mandatory company meeting convened at 12:00PM, with nary a crumb of food in sight, to allow management to make their big announcement:

"We're opening an office offshore, and one of the first things we'll be transitioning there is product documentation."

Ah, transitioning: a nice way to say they were firing every US-based tech writer immediately. From that point forward, the engineers would have to send notes on product features to the offshore team, who would then compile the documentation.

Steven was nervous about the prospect. He'd had a good working relationship with the tech writers. They could take his notes, add their personal experiences with the products, and compile it all into something useful (for the rare user who actually bothered to look at the manuals). Hesitantly, he raised his hand. "Will the offshore team be trained on our products?"

"Don't worry. We're working with a consulting company that's helping us hire the best talent available," the meeting presenter assured him with a saccharine smile.

In other words, No way in hell. Steven saw through the ruse, but didn't have the guts to call it out. No one else did, either. After all, no one wanted to give management the idea that perhaps engineers were just as replaceable as tech writers.

They had no choice but to wait and see. With any luck, the hiring firm would find some good writers, at least.

A few weeks later, Steven sent off his first round of notes and crossed his fingers. Unfortunately, what he got back was his own notes copied and pasted into the standard manual template, surrounded with typos and broken English.

No, wait, they hadn't just copied his notes. They'd tried to "improve" upon them. In one case where Steven explained the behavior of a quirky installer, he'd written:

The installer doesn't always guess right about the drive.

The mangled sentence that had limped back from the foreign office read:

The installer doesn't always predict correct the drive.

There were also problems with fonts, indentation, tables, lists—practically every aspect of formatting. Strange, because the offshore techs were supposed to be working with software that handled all the layout and formatting details for them.

Steven's documentation wasn't the only example of this problem. Together, the concerned engineers banded together and demanded face-time with management.

"I give foreign English speakers a lot of credit. I'm happy to cut them slack," Steven said once he and others had presented the shoddy documentation. "But if your job is to write English, then you kinda need to understand English spelling, grammar, and idiomatic phrasing. Documentation is the one chance we have to inform users of what they need to know so they don't go off the rails. Offshoring may be cheaper in the short run, but with docs like these, we're gonna end up with a lot more support calls and unhappy customers."

Steven then summoned the bravery that'd eluded him during the initial lunch meeting. "There's no point sending text to the other side of the planet to be pasted into the layout, just so we can clean up the mess they send back. I say we generate the user manuals ourselves and cut out the middleman."

The upper manager squirmed in his chair during an uncomfortable pause. "I see your point. But the user manuals are generated with complicated layout software. This thing has a steep learning curve and big per-seat licensing fees. There's no way we can arrange for the onshore engineering team to use it."

So the documentation text had to be round-tripped through the foreign office. Even when the engineers sent off complete final drafts, they always came back with changes—for the worse. Were the offshore techs bored? Struggling to justify their existence? Whatever the case, Steven and others had to slog through their manuals line by line, marking up errors, and sending them back to be fixed. Maybe.

Once upon a time, the company had paid for quality documentation with US tech writer wages. Now they paid for inferior documentation with sweat, tears, torn hair, US engineer wages, and offshore tech wages. Not quite the savings their leadership had envisioned.

<SHAMELESS PLUG> I've finished the second book in my Sword and Starship series! Harbingers is the direct sequel to Blood's Force. If you like fantasy in your sci-fi (or is it sci-fi in your fantasy?), go check it out at Amazon, iBooks, Kobo, or Nook. </SHAMELESS PLUG>

[Advertisement] Manage IT infrastructure as code across all environments with Puppet. Puppet Enterprise now offers more control and insight, with role-based access control, activity logging and all-new Puppet Apps. Start your free trial today!