I was looking at FrankenLoom this evening, rather than weaving on it. FrankenLoom started as a simple frame loom of the sort that Navajo ladies use to weave those beautiful rugs; but because of a horrible accident during a radiation experiment (or something), FrankenLoom ended up with some bizarre extra attachments. At some point I will finish the triptych taking shape there.
It occurred to me that all the extra bits on FrankenLoom do one thing: They constrain what is possible; and yet they sprouted there to make the current workpiece possible.
A loom with nothing on it is like a blank sheet of paper or a blank screen: Anything is possible. But if you are a handweaver, you know that you cannot weave an "anything". You have to prepare the loom by putting the warp threads in place; and in doing that, you constrain the dimensions, weight, color, and texture of the cloth before you even start making it.
So too with writing. That blank screen could lead you anywhere; it opens up an expanding sphere of infinite possibilities, and so nothing happens at all. We begin to write only after we have set the constraints. What are the limits on the dimensions, weight, color, and texture of this thing I am about to write? In weaving as in writing, the preparatory work to set those constraints is often tedious and formulaic; but in both cases, a few experiences with slapdash preparation teaches us the patience to do it right. When we give thought and care to getting "the boring part" right before we start, "the fun part" is more fun - it goes faster for being more nearly trouble-free, and the finished work is of visibly superior quality.
There's surely a message about deferred gratification in there somewhere; but I've learned to find gratification - and to feel gratitude - in setting the constraints that move me from "anything is possible...what now?" to "this particular project is possible, and it's going to turn out very well." The project schedule, product feature plan, information plan, outline, template, and style guide all set constraints. They are the weapons with which I vanquish the frightful monster that is the blank screen. They are the threads with which I warp the loom on which I weave my words.
Friday, February 27, 2009
Tuesday, February 17, 2009
What do you want?
A friend of mine - I wouldn't say "an old friend"; but definitely a friend of long standing - emailed me this evening with about fifteen great ideas for things to blog about. The one that caught my attention was his suggestion to shine some light on the sleuthing that technical writers have to do to get a project done.
Most technical communicators have stories about having to get product requirements and functional specifications by hook or by crook. Most of us have stories about trying to get product feature information from the engineering/development team. But the detective work needs to start a long time before then. We need to be mindful of this universal truth:
People ask for what they think they can get - not what they really need or want.
Not too long ago, an engineer came to me in a tizzy - a major customer had asked for a special widgetizing device. The engineer had designed it, developed a test plan, and determined what certifications the new MumbleCo Widgetizer would need. Then - oh, my goodness! - he realized that his project would go nowhere without product documentation.
My engineer friend knew I wrote manuals, so he asked me to write a manual for it. He knew he could get that.
I looked at the Widgetizer. I asked some questions.
What problem does it solve?
What do you use it with?
How do you connect it?
Does it matter which of these connectors you use?
Does it require any new software? Does it have any smarts?
It turned out the Widgetizer was a very simple device designed to do a single thing in a single context. It didn't need software. Plug it in and watch it go.
OK, I said, so about this hypothetical Widgetizer manual: What problem do we need to solve?
We need to tell the customer how to install and use it, said the engineer. He did not say we needed to explain how it works. I love working with this guy; in some crucial ways, he *gets it*. But I'm still trying to coax him into asking for what he needs instead of what he thinks he can get.
So: The Widgetizer has three connectors, two of which are interchangeable, and it lets you do one thing once it's installed.
After an hour or so of discussion, we agreed on the product documentation for the Widgetizer: a label on the connector panel to identify each connection, and a single-sheet document that included text and pictures to guide customers in setting up the Widgetizer and using it. When I presented the finished material for review, my engineer friend agreed that the Widgetizer sheet covered everything a customer would ever need to know in order to use the product successfully. We decided to have it printed commercially and folded up in the box with the Widgetizer. We all lived happily ever after.
I never did write a manual for the Widgetizer. Sometimes I wonder, though, whether there are any customers longing for a 20-page Widgetizer manual.
If so, I hope they'll ask for what they want rather than what they think they can get.
Most technical communicators have stories about having to get product requirements and functional specifications by hook or by crook. Most of us have stories about trying to get product feature information from the engineering/development team. But the detective work needs to start a long time before then. We need to be mindful of this universal truth:
People ask for what they think they can get - not what they really need or want.
Not too long ago, an engineer came to me in a tizzy - a major customer had asked for a special widgetizing device. The engineer had designed it, developed a test plan, and determined what certifications the new MumbleCo Widgetizer would need. Then - oh, my goodness! - he realized that his project would go nowhere without product documentation.
My engineer friend knew I wrote manuals, so he asked me to write a manual for it. He knew he could get that.
I looked at the Widgetizer. I asked some questions.
What problem does it solve?
What do you use it with?
How do you connect it?
Does it matter which of these connectors you use?
Does it require any new software? Does it have any smarts?
It turned out the Widgetizer was a very simple device designed to do a single thing in a single context. It didn't need software. Plug it in and watch it go.
OK, I said, so about this hypothetical Widgetizer manual: What problem do we need to solve?
We need to tell the customer how to install and use it, said the engineer. He did not say we needed to explain how it works. I love working with this guy; in some crucial ways, he *gets it*. But I'm still trying to coax him into asking for what he needs instead of what he thinks he can get.
So: The Widgetizer has three connectors, two of which are interchangeable, and it lets you do one thing once it's installed.
After an hour or so of discussion, we agreed on the product documentation for the Widgetizer: a label on the connector panel to identify each connection, and a single-sheet document that included text and pictures to guide customers in setting up the Widgetizer and using it. When I presented the finished material for review, my engineer friend agreed that the Widgetizer sheet covered everything a customer would ever need to know in order to use the product successfully. We decided to have it printed commercially and folded up in the box with the Widgetizer. We all lived happily ever after.
I never did write a manual for the Widgetizer. Sometimes I wonder, though, whether there are any customers longing for a 20-page Widgetizer manual.
If so, I hope they'll ask for what they want rather than what they think they can get.
Sunday, February 15, 2009
Manuals are not the point
With the sole exception of my first technical writing job, every time I've been hired as a writer, it's been by someone with a vague notion that their organization needed manuals. More manuals, better manuals, up-to-date manuals.
We technical writers tend to justify our jobs by saying our employers or clients need manuals and help systems, and usually that's where it ends. We sound like Mr. L. Prosser, the road construction foreman in the opening of Douglas Adams's book, The Hitchhiker's Guide to the Galaxy, justifying the demolition of the protagonist's house by explaining that they're building a highway bypass, and "you've got to build bypasses." Press a technical writer to explain why our employers or clients need manuals and help systems, and things get vague fairly quickly.
The truth is, you don't need manuals. You need the right product documentation, delivered in the right medium to meet your customers' needs. The business case is very simple: It saves you money, and it saves your customers money.
The wrong material, though - a poorly organized manual, or a help system that focuses on what the product or service does instead of the tasks your customers want to accomplish with it - is worse than no manual at all. It frustrates your customers. It undermines their confidence in your product or service.
The right product documentation gives your customers the confidence to set up your product or service and become proficient with it faster than they would otherwise. Just by reducing your customers' time to success, you've saved them money.
Beyond building your customers' confidence and getting them from zero to success quickly, you've also avoided the all-too-common technical support call in which the customer says plaintively, "I can't figure out how to set this up." If your organization doesn't have a technical support function, your engineers or developers may be the ones talking your customers through basic steps. All the goodwill in the world won't make up for the drain on their time and the interruption of their thought processes. Worse, if a customer has trouble using the product documentation and places a technical support call instead, you've just induced and reinforced this costly behavior.
With the right product documentation, your customers feel confident enough to take their first steps without asking for help - and when they realize they can easily find the answers to their questions in the documentation, they only call technical support if something isn't working right. Your engineers spend their time engineering, your developers keep on developing, and your customers gain confidence in your product or service.
We technical writers tend to justify our jobs by saying our employers or clients need manuals and help systems, and usually that's where it ends. We sound like Mr. L. Prosser, the road construction foreman in the opening of Douglas Adams's book, The Hitchhiker's Guide to the Galaxy, justifying the demolition of the protagonist's house by explaining that they're building a highway bypass, and "you've got to build bypasses." Press a technical writer to explain why our employers or clients need manuals and help systems, and things get vague fairly quickly.
The truth is, you don't need manuals. You need the right product documentation, delivered in the right medium to meet your customers' needs. The business case is very simple: It saves you money, and it saves your customers money.
The wrong material, though - a poorly organized manual, or a help system that focuses on what the product or service does instead of the tasks your customers want to accomplish with it - is worse than no manual at all. It frustrates your customers. It undermines their confidence in your product or service.
The right product documentation gives your customers the confidence to set up your product or service and become proficient with it faster than they would otherwise. Just by reducing your customers' time to success, you've saved them money.
Beyond building your customers' confidence and getting them from zero to success quickly, you've also avoided the all-too-common technical support call in which the customer says plaintively, "I can't figure out how to set this up." If your organization doesn't have a technical support function, your engineers or developers may be the ones talking your customers through basic steps. All the goodwill in the world won't make up for the drain on their time and the interruption of their thought processes. Worse, if a customer has trouble using the product documentation and places a technical support call instead, you've just induced and reinforced this costly behavior.
With the right product documentation, your customers feel confident enough to take their first steps without asking for help - and when they realize they can easily find the answers to their questions in the documentation, they only call technical support if something isn't working right. Your engineers spend their time engineering, your developers keep on developing, and your customers gain confidence in your product or service.
Thursday, February 12, 2009
No more peanut butter sandwich exercises, please
It seems as though any time I meet someone and the conversation turns to what each of us does for a living, as soon as I say "I'm a technical writer," my partner in conversation is seized with a desire to tell me about some technical writing exercise in high school or college. "The prof showed us a cheese slicer, the kind with a wire and an adjusting knob, and told us to write instructions for using it. We were supposed to write it for someone who had never seen one - like a Martian or something."
My daughter told me about the peanut butter sandwich "technical writing" exercise, made livelier when the teacher dipped her hand into the peanut butter because nobody had specified that a butter knife be used. My own brush with this kind of exercise involved describing an everyday object in exacting detail, as if making a mechanical drawing with words, and explaining what each part of it does.
All these "technical writing" exercises seem to bear that same requirement: Write it for an audience that has no idea what you're talking about. They are all entertaining exercises - if you are fond of useless precision and work for work's sake - but they have almost nothing to do with technical writing. Can we please stop inflicting this silliness on students?
Never in my career have I written instructions for installing and using a frabbetizer, and expected that the people reading those instructions would be completely ignorant of the appearance and purpose of a frabbetizer. The instructions are in the box with the frabbetizer, or the frabbetizer help is part of the frabbetizer download. One way or another, they've got the silly thing in front of them; nobody ever reads a manual on the bus. So I don't have to describe the frabbetizer, beyond pointing out where to connect things or find non-obvious controls. In most cases, they know what it's for already, or they wouldn't have bought it. To address the case of the guy who's mystified by the box that the receiving department just left on his desk, I'll write a paragraph at the beginning of the manual that briefly describes what the frabbetizer is for, and includes some magic feel-good words: "The Model 2500 frabbetizer is a powerful, compact, and cost-effective reputation-polishing device for small organizations. Its small footprint, attractive walnut case, and unsurpassed ease of use make the Model 2500 a popular choice in home offices and start-up businesses." OK, now you know what a frabbetizer is, if you didn't before.
Having ensured that the reader knows what a frabbetizer is, our next step is to talk about all its parts and explain what each of them does, right? Wrong. Nobody cares what the parts do. So we're not going to do that.
Our next step is to talk about what the reader can do, and how to do it. Here's how to switch on the power; here's how to log on; here's how to set up your account; here's how to polish your reputation using the frabbetizer. We are not ever going to get into the nuts-and-bolts details of exactly how the frabbetizer polishes reputations, because nobody cares. Correction: no customer cares. That's all that matters.
Of all the sins a technical writer can commit, there is no sin so great as boring the reader with useless information - and that's exactly what those classroom "technical writing" exercises do. So let's put a stop to it. Students would be better served if the exercise involved identifying the audience for whom they are writing, and writing to the appropriate level.
My daughter told me about the peanut butter sandwich "technical writing" exercise, made livelier when the teacher dipped her hand into the peanut butter because nobody had specified that a butter knife be used. My own brush with this kind of exercise involved describing an everyday object in exacting detail, as if making a mechanical drawing with words, and explaining what each part of it does.
All these "technical writing" exercises seem to bear that same requirement: Write it for an audience that has no idea what you're talking about. They are all entertaining exercises - if you are fond of useless precision and work for work's sake - but they have almost nothing to do with technical writing. Can we please stop inflicting this silliness on students?
Never in my career have I written instructions for installing and using a frabbetizer, and expected that the people reading those instructions would be completely ignorant of the appearance and purpose of a frabbetizer. The instructions are in the box with the frabbetizer, or the frabbetizer help is part of the frabbetizer download. One way or another, they've got the silly thing in front of them; nobody ever reads a manual on the bus. So I don't have to describe the frabbetizer, beyond pointing out where to connect things or find non-obvious controls. In most cases, they know what it's for already, or they wouldn't have bought it. To address the case of the guy who's mystified by the box that the receiving department just left on his desk, I'll write a paragraph at the beginning of the manual that briefly describes what the frabbetizer is for, and includes some magic feel-good words: "The Model 2500 frabbetizer is a powerful, compact, and cost-effective reputation-polishing device for small organizations. Its small footprint, attractive walnut case, and unsurpassed ease of use make the Model 2500 a popular choice in home offices and start-up businesses." OK, now you know what a frabbetizer is, if you didn't before.
Having ensured that the reader knows what a frabbetizer is, our next step is to talk about all its parts and explain what each of them does, right? Wrong. Nobody cares what the parts do. So we're not going to do that.
Our next step is to talk about what the reader can do, and how to do it. Here's how to switch on the power; here's how to log on; here's how to set up your account; here's how to polish your reputation using the frabbetizer. We are not ever going to get into the nuts-and-bolts details of exactly how the frabbetizer polishes reputations, because nobody cares. Correction: no customer cares. That's all that matters.
Of all the sins a technical writer can commit, there is no sin so great as boring the reader with useless information - and that's exactly what those classroom "technical writing" exercises do. So let's put a stop to it. Students would be better served if the exercise involved identifying the audience for whom they are writing, and writing to the appropriate level.
Wednesday, February 11, 2009
The trouble with naming things
It's hard to think up a good name.
In many "primitive" cultures, naming is a magical act. To name is to define. Knowing the true name of a person or thing confers power over it.
Maybe we're more primitive than we'd like to think. Years ago, when I heard about a guy running for mayor in Austin, Texas, I thought "That guy was born to go into politics." His name is Will Wynn, and he did win.
But when you're on the spot and you need to name something - a business, a product - it's hard to think up a good name.
Part of what makes it hard is that a name may mean something you didn't mean it to. I know of a company that designed a new high-tech product and planned to call it the model 420. (If that is not a funny statement to you, go to Wikipedia and enter 4:20 in the search box.)
Complicating matters is the fact that a set of sounds may mean nothing in your language but might have a meaning in some other language. Another company I know of once planned to introduce a new product as the "VQ", until a French person explained that they had best call it something else. ("Vieux queue" is not a phrase normally uttered in a business context.)
Then too, no matter how innocuous and straightforward the name, some people are going to mess with it if they possibly can. My daughter shops at a store called Grocery Outlet. Being a wise-acre college student, she shortens the name to "Groce-Out".
Even the pros goof up some of the time. In one of those two bad-product-name anecdotes, a product naming consultant was paid a huge amount of money and still ended up presenting an unusably bad product name.
I don't have a good answer to the problem of coming up with a good name, other than trying it out on as big and diverse a collection of people as possible. So I'll just hope I don't end up the subject of a story about a poorly chosen name.
In many "primitive" cultures, naming is a magical act. To name is to define. Knowing the true name of a person or thing confers power over it.
Maybe we're more primitive than we'd like to think. Years ago, when I heard about a guy running for mayor in Austin, Texas, I thought "That guy was born to go into politics." His name is Will Wynn, and he did win.
But when you're on the spot and you need to name something - a business, a product - it's hard to think up a good name.
Part of what makes it hard is that a name may mean something you didn't mean it to. I know of a company that designed a new high-tech product and planned to call it the model 420. (If that is not a funny statement to you, go to Wikipedia and enter 4:20 in the search box.)
Complicating matters is the fact that a set of sounds may mean nothing in your language but might have a meaning in some other language. Another company I know of once planned to introduce a new product as the "VQ", until a French person explained that they had best call it something else. ("Vieux queue" is not a phrase normally uttered in a business context.)
Then too, no matter how innocuous and straightforward the name, some people are going to mess with it if they possibly can. My daughter shops at a store called Grocery Outlet. Being a wise-acre college student, she shortens the name to "Groce-Out".
Even the pros goof up some of the time. In one of those two bad-product-name anecdotes, a product naming consultant was paid a huge amount of money and still ended up presenting an unusably bad product name.
I don't have a good answer to the problem of coming up with a good name, other than trying it out on as big and diverse a collection of people as possible. So I'll just hope I don't end up the subject of a story about a poorly chosen name.
Subscribe to:
Posts (Atom)
Posts
.jpg)