Got Some Explaining To Do

“I’m a doctor, Jim, not a cable modem technician!”
“I’m a doctor, Jim, not a..”"I’m a doctor, Jim, not a bricklayer!”
“I’m a doctor, Jim, not a command shell!”

I just searched on “I’m a doctor, Jim” and got around 700 hits. Lately I’ve been emphatically repeating something similar: “I’m a technical writer, not a ___” Much of the writing I’ve been attempting to do fills in that blank. I’m not sure what you call it. It’s the writing for the Flock web site, revision two, and I’m pretty sure I’m the wrong person to be doing it. Oh, I can explain things. I can explain how the Star and Tag dialog works till the cows come home. (Fortunately, it doesn’t take that long.) But I can’t come up with a snappy little phrase to capture the essence of Star and Tag. No, I couldn’t do that if my very life depended on it. The best I’d come up with is some sort of feeble phrase that screams “DORK!!!”

So what is a technical writer? In this age, a technical writer is someone who consumes information about about complex subjects, and produces an explanation, written in terms that can be understood by pretty much anyone with a moderate degree of education.

I’m also an instructional designer. An instructional designer analyses material a reader needs to learn, and figures out the best, most logical way to present that information. An instructional designer asks questions like, “What are the characteristics of my readers? What tasks do they want to do? What do they need to know in order to do these tasks? What vocabularly do they understand?” And so forth.

So I am an explainer. The kind of writing I do has more in common with teaching than with writing catch phrases. In fact, writing catch phrases can be the opposite of technical writing, because eye-catching exclamations — You’ve come a long way, baby! — often obfuscate. They do not explain.

I’m not saying that it’s impossible for me to coin a phrase. I do that, sometimes. Maybe about once or month or so.

Yesterday, when I said something like the above rant to a colleague, he responded, “Don’t thrash yourself!” He doesn’t understand. I’m not thrashing myself. I don’t feel bad that I can’t write “that way.” If anything, by my way of thinking, I’m complimenting myself.

If I had to choose one bit of technical writing as the piece that makes me most proud, it would be an online document I wrote while at Netscape, on the subject of Internet privacy and security. It explained in simple terms many of the issues concerning people at the time: what is a cookie, how does encryption work, how does one choose a good password, is it safe to use a credit card online, etc. In the process of writing it I had to read about and understand encryption. And as I’ve told my daughters many times, you know you understand a subject when you can explain it to someone else.

I see my role at Flock as threefold. First and foremost, I want to help make sure that our software explains itself. Self-explantory software is my holy grail. Second, I want be the managing editor of a database of information, some of which I author, that is a resource for people who have questions about Flock or want to learn more. And finally, I want to be Flock’s information architect, and try to create appropriate structure for the flood of information we will inevitably produce (because all high tech communities do).

And now, because I like to be perverse, I will close this post with a catchy tag line that captures the essence of what it is that I do.

“I’m a technical writer. I’ve got some explaining to do.”