Home - is where I want to be / But I guess I'm already there /I come home -
she lifted up her wings /
Guess that this must be the place...
- Talking Heads, "Naive Melody"

Thursday, March 20, 2008

Nothing Personal

I spent all day Wednesday in a session with our support team and one of the developers, taking notes as they followed the installation guide I wrote to try to install one of our more problematic products. By the end of it, I had two pages of notes, a lot of questions that need to be answered, and can't say I was feeling any too good about the job I'd done.

One of the hardest parts of writing comes in taking criticism. What we write is extremely personal, whether it's a letter, a novel, or an installation guide; it comes directly from our minds into its final form, without mediation. So it is difficult, when the criticism comes in, not to feel ourselves attacked, to get defensive, to offer up excuses for why information is missing, or hard to find, or just plain wrong.

Difficult, but vital. It's one of the more annoying universal truths that the easy way is almost always wrong. No piece of writing is perfect in its first draft, and sometimes we're too close to see the problems. Taking feedback and making the necessary judgments--is this really a problem? will the suggested change help? or is this person off their rocker? is part of the craft.* Ignoring feedback cuts us off from one of the main ways we can improve our writing, and encourages writing from habit rather than thought. If I can't answer the question, "Why did you do that/do it that way?" I am not writing well.

The upshot of yesterday's exercise is that I didn't do the best job I could have done with the documentation. Having given myself a few minutes to sulk about how it's not my fault, it is now time to fix it. In a few weeks I'm going to sit down with this team again, and we'll do the whole test again, and see if it's better.

*I am in the "tech writing is craft, not art" camp, in case anyone cares. Perhaps I'll post more on that subject at some point.

No comments: