Does it have a hyphen?

Years ago, I discovered that the surest way to throw a roomful of technical writers into an uproar is to ask, as innocently as possible, "Does the term 'anal-retentive' require a hyphen?"
Don't take my word for it. Try it yourself - but only if you've already concluded the business at hand, and still have an hour or two to spare.

Spirited discussions of grammatical questions are like crack for writers. They give us such a buzz every time. We feel so great, so smart, so right. It's what we live for. We can't stop. We can't get enough. We don't want to hear that they interfere with our lives and damage our productivity, and we really don't want to hear that they're an inappropriate use of a designated meeting time or discussion forum.

The only difference between writers and crackheads is that we're not likely to get arrested for possessing grammar books. Today I witnessed this truth play out in a dramatic, time-consuming, and very public way.

As in music or dance, it's impractical to strive for perfection in writing. We have to settle for attaining a level of skill that allows us to make a living at it. And our goal must be to communicate effectively, rather than to be excruciatingly correct. A technical writer's mission is to help people understand things. If we have to make a choice between clarity and correctness, we have a professional obligation to choose clarity; though in almost every case a bit of rewriting will allow us to serve both those masters.

Most of us are acquainted with the anecdote usually attributed to Winston Churchill: Upon seeing one of his sentences rewritten in a cumbersome fashion to keep it from ending with a preposition, Mr. Churchill allegedly said "This is the sort of nonsense up with which I will not put."

Regardless of the true origin of the quote, the point is valid: Clear communication is the objective. Get the grammar right enough that it doesn't interfere with your message - that is, right enough that it doesn't strike your audience as wrong - and move on. It's one more matter that comes down to knowing your audience, and recognizing that sometimes tech writers are not the audience.

I might get into tech writing

"Hey, how are you doing? What have you been up to, the last few months?"
"Oh, I'm doing all right. Looking for a job, though."
"Yes, I got laid off recently, too."
"You know, I was just thinking about getting into technical writing..."

This conversation bothers me every time I find it playing out - which it does so often I wonder if I'm in a time loop, like "Groundhog Day". The last time around, a few days ago, it was time to dig into the question of why it bothers me.

I know this is meant as an expression of interest in my trendy and lucrative profession. I know it is not meant a subtle variant on "Anybody can write."

Still, I can't picture myself saying to my friend, "You know, I've been thinking about getting into engineering," or "I've been thinking about getting into project management." I would sound presumptuous, at least to my own ears. I've been a technician and and engineering assistant, but I don't have the training to be an engineer. I took the coursework from the Project Management Institute, but did not sit for the PMP exam. If I were to consider becoming an engineer or a project manager, I would need to start by becoming qualified to do the work.

Within the Society for Technical Communication, the idea of certification for technical communicators resurfaces from time to time; to date I've opposed it because the Society hasn't ever worked out what that would entail. But now an effort is under way to develop a body of knowledge (BoK), which has been the missing piece. Once the Body of Knowledge is declared ready for use, I will have a helpful answer to my friends who speak of becoming technical writers. I'll be able to point at it and tell them, "Here is a good place for you to start."

The STC Body of Knowledge is in progress at http://stcbok.editme.com/ - take a look, or contribute.

Reclaiming the boxes

A good friend just called me out - and properly so - for neglecting my audience (well, he said my blog) for so long.
I'm sorry.
Forgive me, readers, for I have sinned. I did not meet your expectation that I'd say something from time to time. I committed the writing sin of letting the material get stale. I demonstrated poor work habits by failing to treat this blog as work. Mea culpa. This is one time when it would have served me better to do a very 20th century thing: compartmentalize all the messy bits of my life.

Remember compartmentalization? It was the notion that you could chop up your life into chunks and put aside the bits you didn't want to think about at any given time. Remember what a bad reputation it had? Such an unhealthy thing to do - denying parts of your experience, your personal narrative. We're so much more emotionally healthy if we throw away all those little boxes that we use to compartmentalize our lives. And a lot of people did that.

You can identify the people who threw away the boxes, and don't approve of compartmentalization. The extreme cases are the ones at the next table over in your favorite restaurant, Having Issues (maybe even breaking up) in public; the ones in the office who are always on the phone, talking to friends about other friends, doing that thing we call "homing from work".

My office is in my house now. I was once skilled at compartmentalizing the parts of my life that don't need to come to work with me, but changing the way I work is changing the way I handle the rest of my life, too. I think I've still got the mental boxes for compartmentalizing my life; they've just gotten a bit muddled up. I work at home; does this go in the work box or the home box? It's easy to get sloppy.

Some things happened recently in my personal life, and rather than risk having them spill into the professional side of my life, I stopped blogging for a while, on the theory that it's just my blog and I can take a break if I want to. That wasn't a good way to deal with things. Old-school compartmentalizing would have served me better.

You'd think that after living through a couple decades of radical changes in people's assumptions about how we work and why we work and what we do for a living, I'd be better at adapting - but this isn't a matter of learning anything new; it's a matter of going back to what was considered good business etiquette a generation ago. Clothing styles from the '70s are back; maybe it's time to give retro work habits another look, too.

I've spent the last two weeks grinching and groaning and generally boring people with updates on my car, as that sad tale unfurls in a leisurely fashion. Bumper sticker version: My car got badly damaged by hail, and was declared a total loss - but only after it was declared worth repairing, and I'd gotten my hopes up.

This morning it dawned on me that I was dealing with this sudden, forced change - give up my sweet car? no no no! - exactly the way people "down the food chain" in organizations deal with sudden, forced change; which is to say, exactly the way four-year-olds deal with it.
I want my doll back! Make her be not broken!
I want my car back! Make it be not broken!
I want my business process back! Make it be not broken!

The irony is that I'd just told someone "You need to let go of this process you use; it's broken."
And of course I'd gotten back, "No no no! I want my process! It isn't broken, its head is supposed to come off like that!"

For years I've known in my head that you have to manage change carefully to introduce it successfully. You've got to get people excited and happy about what's going to be different; otherwise they'll resist it in every way they can. Over the last two weeks I've been absorbing that lesson into my heart.

I should go give blood while my irony level is up so high.

Packaged on: 05APR09 Sell by: 04APR10

I just looked at the date on my last post - it's very stale material by now. I'm sorry. There were reasons for the silence; chief among them being that sometimes it's the better part of valor to sit down and shut up. (Natural disaster, badly damaged car, much to-ing and fro-ing with insurance company and body shop, if you must know.)

But I'm back now.

Recently I saw some product documentation that clearly needed work. Certainly it needed the deft touch of a good technical writer; but what struck me first and hardest was that it needed to look like a product of this millennium. It seems the company had designed their documentation and the process for creating it some time in the mid-1990s, and had been using early documents as templates for later ones ever since. Meanwhile the world kept on advancing; and with it, documentation conventions, tools, and best practices.

With few exceptions, we need to step back and look at our organizations' product documentation about every three years, or every time our colleagues the marketing specialists update the appearance of the company web site and marketing materials. During these periodic reassessments, we need to ask ourselves, "Does this material reinforce our organization's main message? Does its appearance reinforce and expand upon the first impressions that our marketing material and web site create? Does this look like it comes from the same company?" We also need to consider whether we still deliver our material in the way customers expect to see it. Are we still writing software manuals instead of providing help? Are we still using section numbering when all our competitors have stopped doing so?

Marshall McLuhan said "The medium is the message", and that's far truer now than it was when he said it. The words and pictures are not the sum of your product documentation. The words, pictures, look and feel, and delivery method all work together to produce a powerful message about the product and the company. It behooves us to ensure that the message never becomes "We have been doing it this way for the last fifteen years and we're not about to change."

Tina the Technical Writer doesn't work here

If you're a technical writer, you may have had this experience:
The new guy on the product support help desk walks in, holding the system administrator's guide that you designed, researched, wrote, and illustrated. He scans your cubicle, looking for signs of - heaven only knows what, but clearly it's not there.

Help desk guy: "Hey, I just started here and they handed me this manual. It's great! Who wrote it?"
You: "Um...I wrote it. I'm the technical writer."
Help desk guy (gawking): "YOU wrote it??"
You: "Yes. That's my job. I write the manuals. I write the help, too."
Help desk guy: "Who helped you with it?"
You: "Each of the developers answered my questions about the features they own, and they each reviewed the topics where their features are discussed."
Help desk guy (floundering): "But...I mean...how did you know what to write?"
You: "I started with the product requirement documents and the feature design documents, and I spent a lot of time playing with the product as soon as it was stable enough for me to poke around at it."
Help desk guy: "You actually use the product?"
You: "Sure. There's really no other way to get familiar with it, and I have to understand it myself before I can help other people understand it."
At this point the help desk guy generally wanders off to recover from having his world rocked.

If you've ever had that conversation with the disbelieving help desk guy, you know the source of his disbelief and your frustration: Enough people have encountered non-stellar tech writers that stereotypes exist. You can't change that. Neither can I. The only thing we can do is choose not to conform to the stereotypes.

So forget Tina the Technical Writer, the character in Dilbert. She's a cartoon character. Roll up your sleeves and get into the technical details of the thing you need to explain to your customers. Tell your developers when you spot things that may cause problems for customers - "Can you build some validation into this field? Right now, this form lets me build a test condition that's nonsense." Focus on what you do best and let the stereotypes take care of themselves. It doesn't take long for people to realize that whatever they expected, in you they've got a person who readily grasps technical concepts, is passionate about communicating useful information to people who need it, and visibly contributes to the organization's success.

The idea that wouldn't die

Some ideas sound great for about five seconds, and then gracefully go away. Some sound uninspiring at first, but gradually reveal their brilliance. And some ideas sound like Manhattan Projects for opening pickle-jars, but they just won't go away. Exhibit A in this category is the idea of certifications for technical writers.

Full disclosure first:
I do not meet the educational requirements so loved by personnel departments. I have never studied journalism or English, beyond the bare minimum. I do not have a bachelor's degree in anything. I have a trade-school degree in electronics. I became a technical writer more or less by accident. So I don't like the idea because it might mean my résumé and sheaf of awards might not be enough to get me in the door for interviews.

Let's step back, though, and think about this.

What problem are we trying to solve?
There's no arguing the fact that in every profession, there are people who just aren't any good at what they do; and it's hard to get rid of them once you've hired them. It would be easier if there were a way to avoid hiring them. There is; but it requires knowing something about the work. Organizations hiring their first technical writers don't have that expertise; but they need to get it right the first time. So there is a real business problem to be solved.

Many professions use certifications, some with more success than others. I respect people who are certified project management professionals. I know the effort it represents, and I know the range of skills upon which it focuses. I respect people who have been certified as professional engineers; again, I know that the letters "PE" after the name represent a great deal of work and a fair degree of skill.

I'm not nearly as comfortable with teacher certification, because I'm not persuaded that it's meaningful. I've dealt with far too many teachers who could be described at best as mediocre. Go ahead and flame me. In ninth grade I had a science teacher who could not do sums. (Hey, here in Texas we are all about equal opportunity.) Is it possible to create technical writing certifications that are more meaningful than teacher certifications?

To be useful, certification needs to do three things:

• Correctly identify the essential skills of the profession.
• Assign them appropriate importance relative to one another.
• Test them in a valid way.

The sheer diversity of work that comes under the heading of "technical writing" makes it difficult even to identify a core skill set. Is there a meaningful "common denominator" among all the skills represented in our profession?

I was once hired as a technical writer for a job that involved no writing at all. I was to add conditional text tagging to existing material in such a way that the team could produce manuals for new products without changing the text and conditions already in place for existing products. I have had technical writing jobs that included extended periods of creating pictorial instructions only. One might think that any technical writer should have an excellent command of grammar and punctuation; but would it have been meaningful to require proficiency in grammar and punctuation in these situations?

Should we even think of technical writing as a single profession?

Many have suggested specialized certifications to address this. But technology moves quickly, while certifying bodies move slowly. What's going to be the good of having a ten year old certificate in web design? The only solution I can see is to certify people's understanding of concepts rather than implementations. Don't certify people in web design; certify their understanding of usability, searchability, and accessibility. Don't certify people in writing manuals; certify them in organizing information and knowing when to show rather than tell.

That might actually work.