Argh! You Wrote A and They Published B

One of the most frustrating moments in a tech writer’s life can come after the job is long over. Weeks later, you get your hands on the finished product, which looks great, but suddenly you see something that makes you crazy.

The sentence (or label, or punctuation mark) that you polished till it gleamed has been mangled. You wrote it one way, but they published something different.

You’re the writer. You’re the one who people point to when the copy is bad. But in the end, if the developers happen to change something just before they lock down the code, you’ve got a very slim chance of going in there to change it back. It’s just copy, after all.

After experiencing this enough times to threaten head-explosion, I started a program of nipping-in-the-bud that I still do today. It doesn’t always work, but it’s a far cry from the bad old days.

Understand why it happens

As a rule, developers aren’t out to mock and humiliate you. If they change something, it’s because they think it’s the best thing to do, they didn’t have a choice, or they didn’t think much about it.

Example one: You write a dialog box like this:

Are you fond of baby elephants?

<YES BUTTON>  <NO BUTTON>

But let’s say that the developers can’t easily create “Yes” and “No” buttons in that particular dialog box. It’s possible, of course, but it would take a lot of work.

So they keep as much of your copy as they can, and leave the buttons alone. And you end up with:

Are you fond of baby elephants?

<OK BUTTON>  <CANCEL BUTTON>

You see this and steam comes out of your ears.

Example two: You write this:

Choose the target you’re aiming for.

The developer, whose first language isn’t American English (or Australian English, or wherever you are), remembers his decrepit high school teacher saying not to end sentences with prepositions. So he changes it:

Choose the target for which you’re aiming

But then, that doesn’t fit in the field, so he changes it to:

Choose the aimed for target.

You see this and you go nuts.

So you scream up and down the halls that no one should ever change your stuff. LEAVE IT ALONE. Then comes example three.

Example three: You write this:

Select your favroite item.

The developer spots your typo and… ignores your ranting. He fixes the word “favorite” and calls it a day.

You see this… and you’re happy, but also embarrassed.

The key isn’t to keep them from touching your stuff. They key is to communicate with them.

Understand how to stop it from happening

I’ve found that the best way to handle these issues is to ask the developers to make the changes they think are necessary, and then immediately let me know what happened and why. Most of the time, what they’ve done is just fine. Sometimes it isn’t, so I write back with a change.

This system is better than asking them to work it out with me BEFORE they make the change. The last thing they need is a disruption to their schedule, waiting on hold for a problem that they think they already know the answer to.

The thing to note about this system is that it requires me to respond right away. If I get an email from a developer, I read it, think about it, decide how to handle it, and write back. Immediately. If I can’t answer right away, then I write back to explain so.

I’ve found that by promoting communication, and by respecting the intelligence of the rest of the team, my head-exploding moments have become much more rare than they used to be.

Has anyone else faced this kind of frustration? What do you do to stop it from happening?

No comments yet.

Leave a Reply

Subscribe without commenting