Writing a thing? Do the thing.

Figure holding board that says: do it yourself

Image courtesy of Master isolated images / FreeDigitalPhotos.net

Recently, I went through the process of hiring a tech writer. My boss, who is not a tech writer, sat in some of the interviews and always said the same thing to the prospective writers: “For this job, we’ll need someone who will actually install and operate the software that he or she is writing about.”

And each time he said it, I thought, “well, duh.”

But my boss knows something that I shouldn’t be surprised about. Some writers don’t bother. Some writers don’t follow their own steps as they write (or after they’ve finished writing). Instead, they write from memory or, even worse, from someone else’s memory. Sometimes they write from a spec sheet.

That’s a really bad idea.

First of all, it makes for a less helpful experience for your audience. More on that below. But also, it lowers your value as a professional. We’re supposed to be the people who think like the audience. We can see things from a different perspective and catch problems that other people don’t see. If a writer is merely someone who take specs and puts them in a different format, then you may as well hire an intern. Sometimes you have no choice but to write from spec (like if the product hasn’t been created yet and there’s no time in the schedule for writing later). But the cold fact is that the end result is worse when we don’t do it ourselves.

Rather than rail about it, I’ll just give you a recent example of something that was written well enough, but was still a bad experience for me.

The example

I needed to temporarily remove a little program called Silverlight from my computer. I checked the help, and on a good note, there WAS some. I just needed to delete a few files. (There was also a link to a separate page on how to “uninstall” the files, which amounts to “find them and delete them.”)

The writer put the files in order of the file type. First you delete all the siliverlight files, and then you delete the WPFE files. Now, it doesn’t really matter which ones you delete first, but most people would start at the top and go down.

Here’s a screen shot of the page:

Steps to uninstall silverlight

So what’s wrong? Well, have a look at where the files are actually located. The first one is in the “Internet Plug-ins” folder. The second and third are in the “Receipts” folder. Fine so far.

But wait! The fourth file is in the “Internet Plug-ins” folder. Wasn’t I just there? And then, for the cherry on top, the fifth one is back in the “Receipts” folder!

That means that to delete files in two folders, I’ve just navigated to a folder FOUR TIMES!

There is no way that a writer went through that process without realizing that something was wrong. So my guess? The writer didn’t bother going through the process.

And this isn’t even really a process! It’s just a list of files to delete. Imagine all the little gotchas that can happen when you have 5 or 10 steps to follow. I guarantee that there will be little things that you don’t know about until you do it yourself,

To put it more poetically: You can’t lead your audience through your product by standing behind them and pointing. You have to go first.


No comments yet.

Leave a Reply