...need project management.
(Full disclosure: This post is not about technical communication.)
Our resolutions tend to shape up as long wish lists that detail our individual perceptions of fabulousness and how we deviate from that ideal - rather like the grab bag of cool features that everyone wants to add to a product in its next release. And like that long feature list, our lists of resolutions contain many items that will be dropped, and a couple keepers.
In a product development project, it's OK for features to fall off the must-do list. But when that happens with one of our New Year's resolutions, we feel guilty about it. To make up for it, we make more unrealistic resolutions, fail to keep them, and feel guiltier: Jeez, this same thing happened *last* year! I can't even keep a crappy resolution! I'm a failure because I didn't pay off all my debt, lose 25 pounds, go to the gym three times a week, quit smoking, and write to my mom once a week! I'm a failure! I have to try harder! I know, I'll do charity work and give blood!
OK, STOP IT RIGHT NOW.
In product development, a successful product release usually has just one or two "wow features", along with some minor changes. Try applying this idea to your resolutions.
What's your wow feature for 2010? Pick ONE - just one. Are you going to quit smoking? If you keep that resolution, nothing else matters. The same is true for paying off all your debt, losing 10 pounds or more, or adopting a regular schedule of exercise. Decide to do any one of those things, and if you want it to happen, you'll be able to do it - and make a huge improvement in your life. Try to do more than one of them, and you're likely to fail. So pick one.
If you feel that you should have more than one resolution, pick your "wow resolution" and then make a handful of BS ones that you'll be able to keep without much effort:
I resolve that I will not let my household run out of coffee or beer in 2010.
I resolve that I will put a new roll of toilet paper on the roller if I use the last of the old roll.
I resolve that I will get my car's oil changed in accordance with the manufacturer's recommendations.
I resolve that I will always tip at least 20% unless I receive really craptacular service, in which case I'll leave a note explaining why I felt the service was bad.
I resolve that I will put paper in the printer instead of waiting for someone else to do it.
Not all product releases have wow features. Some are just bug-fix releases, which are what they sound like. You could decide that 2010 is a bug-fix year, and not have a wow resolution. How about just a handful of bug-fix resolutions, aka BS resolutions that will be easy to keep?
After 2009, that's an attractive idea, don't you think?
Sunday, December 27, 2009
Monday, October 12, 2009
A glass half-full of new wine
A while back, I encountered a former business associate at a coffee shop and explained to her that I was embarking upon a career change. She told me I was overdue - on average, she said, people change careers every seven years.
Seven years - is that all? It's probably going to take me seven years to stop viewing the world through technical-writer-colored glasses. Navigating the intricacies of the red tape surrounding the training program I'm in, I've been documenting and reporting what it's taken to get things done. Looking through my new Cisco networking book today, my mental editor had her blue pencil out. Even so, I was a lot more mentally engaged with the idea of scoring a free motherboard. This tells me my mind-set is starting to move.
I'm still getting inquiries about my technical writing services from potential clients, some of whom seem intrigued at the idea of a technical writer with IT chops. For all I know, this may be less a career change than a specialization. But I'm excited about the possibility of doing something totally other than writing for a living.
The future looks frightening when you look forward and see only a wall; but when you look forward and see a multitude of paths, it's hard to be anything but optimistic.
Seven years - is that all? It's probably going to take me seven years to stop viewing the world through technical-writer-colored glasses. Navigating the intricacies of the red tape surrounding the training program I'm in, I've been documenting and reporting what it's taken to get things done. Looking through my new Cisco networking book today, my mental editor had her blue pencil out. Even so, I was a lot more mentally engaged with the idea of scoring a free motherboard. This tells me my mind-set is starting to move.
I'm still getting inquiries about my technical writing services from potential clients, some of whom seem intrigued at the idea of a technical writer with IT chops. For all I know, this may be less a career change than a specialization. But I'm excited about the possibility of doing something totally other than writing for a living.
The future looks frightening when you look forward and see only a wall; but when you look forward and see a multitude of paths, it's hard to be anything but optimistic.
Saturday, August 8, 2009
Waking up is hard to do
Change is hard.
Challenging your own assumptions is hard.
Waking up and realizing that you need to change is enough to send a lot of people back to bed. It's so hard that many people, confronted by the need to change, don't change. So people stay in relationships that no longer work. So people become old and bitter from decades of doing work they hate. So people die from things they choose not to change - smoking, drinking, other drugs. At some point, the cost of changing becomes smaller than the cost of not changing. If you are fortunate, you wake up and realize that.
My mind realized a couple months ago that I had reached that tipping-point (My job is not me, May 27), but it took some time to accept it in my heart.
I love the process of learning and documenting a technical product - playing with it, asking the engineers how they intended a particular feature to be used, picking the support technicians' brains about what problems make up the bulk of customers' calls to the help desk, comparing notes with the software quality assurance people when I encounter an unexpected behavior. But I still get irritated at having to combat the common perception that "technical writer" means "non-technical person who writes about things she doesn't understand."
I love the process of working out what kinds of information people need, what audiences I must address, and how to chunk up and present the information to meet each audience's needs most effectively. I love the process of creating the process - how will we consistently meet schedules? How will we consistently produce top-quality work? How will we handle version control? How will we ensure that our processes scale as flexibly as the company's product strategy? But I still get irritated at having to combat the perception that somehow, as if by magic, all this takes care of itself for technical writing even though it does not in other areas, because after all it is only writing and anybody can write.
I love working with engineers who know they can "talk tech" to me. I don't love managers who insinuate that they can have the new intern write the manuals instead. (Bubba, I hope you're right about your intern, because I'm not going to do business with you.)
I just woke up and realized that it costs me more to keep calling myself a technical writer than it does to take advantage of the glorious opportunity this recession has handed to me. I've had to work through a lot of internal resistance to change, but I've gone back to school. I've chosen to start a new career doing the thing I had originally envisioned when I started college. I'm studying for my first round of IT certifications.
I'm sure I'll keep on doing technical writing as a sideline, just as I never completely stopped fooling around with electronics; but it's not going to be my whole life any more - and neither is my new career. I've learned the hard way about allowing my job title to trap me in a box.
Challenging your own assumptions is hard.
Waking up and realizing that you need to change is enough to send a lot of people back to bed. It's so hard that many people, confronted by the need to change, don't change. So people stay in relationships that no longer work. So people become old and bitter from decades of doing work they hate. So people die from things they choose not to change - smoking, drinking, other drugs. At some point, the cost of changing becomes smaller than the cost of not changing. If you are fortunate, you wake up and realize that.
My mind realized a couple months ago that I had reached that tipping-point (My job is not me, May 27), but it took some time to accept it in my heart.
I love the process of learning and documenting a technical product - playing with it, asking the engineers how they intended a particular feature to be used, picking the support technicians' brains about what problems make up the bulk of customers' calls to the help desk, comparing notes with the software quality assurance people when I encounter an unexpected behavior. But I still get irritated at having to combat the common perception that "technical writer" means "non-technical person who writes about things she doesn't understand."
I love the process of working out what kinds of information people need, what audiences I must address, and how to chunk up and present the information to meet each audience's needs most effectively. I love the process of creating the process - how will we consistently meet schedules? How will we consistently produce top-quality work? How will we handle version control? How will we ensure that our processes scale as flexibly as the company's product strategy? But I still get irritated at having to combat the perception that somehow, as if by magic, all this takes care of itself for technical writing even though it does not in other areas, because after all it is only writing and anybody can write.
I love working with engineers who know they can "talk tech" to me. I don't love managers who insinuate that they can have the new intern write the manuals instead. (Bubba, I hope you're right about your intern, because I'm not going to do business with you.)
I just woke up and realized that it costs me more to keep calling myself a technical writer than it does to take advantage of the glorious opportunity this recession has handed to me. I've had to work through a lot of internal resistance to change, but I've gone back to school. I've chosen to start a new career doing the thing I had originally envisioned when I started college. I'm studying for my first round of IT certifications.
I'm sure I'll keep on doing technical writing as a sideline, just as I never completely stopped fooling around with electronics; but it's not going to be my whole life any more - and neither is my new career. I've learned the hard way about allowing my job title to trap me in a box.
Thursday, July 30, 2009
If you haven't anything good to say...
If you woke up one day, prepared yourself to face the world, and realized, "My goodness. I have nothing good to say," or worse, "My goodness, I have nothing at all to say," would you say it anyway? Or would you let your blog get one day more stale?
And if that day stretched to a week, or a month, and you found yourself thinking, "My goodness. I still have nothing (good) to say," would you grow alarmed? Would you fault yourself for being lazy and self-indulgent, and firmly compel yourself to manufacture something you could post? Or would you keep silence out of concern that every time you tried to write, you found yourself wasting the time of your readers?
We all know that if you start a blog, you should treat it as a commitment as firm as any job. You should keep it fresh, expound upon matters within your realm of expertise, keep the opinions and advice coming. Stay positive. Build that Brand You. Market yourself nonstop.
But what happens if you DO hit a wall?
You go crunch, silently.
My goodness. I have nothing to say.
And if that day stretched to a week, or a month, and you found yourself thinking, "My goodness. I still have nothing (good) to say," would you grow alarmed? Would you fault yourself for being lazy and self-indulgent, and firmly compel yourself to manufacture something you could post? Or would you keep silence out of concern that every time you tried to write, you found yourself wasting the time of your readers?
We all know that if you start a blog, you should treat it as a commitment as firm as any job. You should keep it fresh, expound upon matters within your realm of expertise, keep the opinions and advice coming. Stay positive. Build that Brand You. Market yourself nonstop.
But what happens if you DO hit a wall?
You go crunch, silently.
My goodness. I have nothing to say.
Thursday, June 4, 2009
Help, I can't find it in the index!
When you need information from a manual or a help system, how do you look for it? Many of us will use the index first, if there is one. Why?
A table of contents is the writer's view of the book. It describes the structure. It tells a story.
If you need to know one specific bit of information, you may not know exactly where you are in that story; and you probably don't care. You just need to know how to change the frabbetizing configuration settings on the MumbleCo unit, and you'd prefer to get it done before you stop and go outside for a smoke.
If your company has recently switched to this product from a competitor's product, you may not know that the appropriate terminology for the setting you want to change on this fine product is "frabbetizing configuration". You may still be thinking in terms of the competing unit from Behemoth Inc., which calls the equivalent setting on its machine "whatsit settings".
If the manual for your new MumbleCo unit has a good index, it doesn't matter whether you know where you are in the table of contents story, and it doesn't matter whether you're up to speed on MumbleCo terminology. You can look up the term you know - "whatsit settings" - and the index teaches you, very gently, "See frabbetizing configuration." And lo, when you look up frabbetizing configuration, there it is, with sub-entries that point you to all the things you might want to know about it.
If the author of the manual has given the index short shrift, you're on your own. Maybe you should take that break before you try to find the information you need.
Fairly often, the index does get short shrift, like all the other things at the back of the book. Making a good index is labor-intensive; there's no good way to automate it, regardless of what the makers of authoring tools would like you to believe. It takes a person asking "What is this paragraph about? What would I have been looking for if my search led me here?" Fairly often, the index entry is a phrase that does not occur in the indexed material. But the fact that it may take 6 to 8 hours per page to create the index does not mean you should skip it.
The index is a reader's random-access information discovery tool, and it is (or should be) the writer's teaching tool. With all due apologies to Adobe, try this experiment: Look for a specific bit of information, using generic terminology, in the help for an Adobe product. For example, in Illustrator, how do you move a vertex to change a shape? You'll see what happens when you overlook the teaching aspect of the index. In Adobe-land, you have to know the terminology already to find the help you need. But who needs the most help? People who have no prior experience with the product, and don't know the terminology. In all fairness, Microsoft is just as bad; I never have been able to figure out if there is a way to change rows to columns and vice-versa in Excel when I decide I've structured my spreadsheet badly. And I have never been able to make heads or tails of the bookkeeping software I bought last year, because I don't know the terminology. In each case, the index fails in its teaching function - it doesn't include plain language that refers me to the specialized term.
The lack of a well-designed index in a manual or help system makes the whole product less usable.
When you work out the schedule for writing a manual or help system, include the time to create an index. In my experience, it will take about a sixth of the total writing time; your mileage may vary. But no matter how much time it takes, do it. Your readers are counting on you.
A table of contents is the writer's view of the book. It describes the structure. It tells a story.
If you need to know one specific bit of information, you may not know exactly where you are in that story; and you probably don't care. You just need to know how to change the frabbetizing configuration settings on the MumbleCo unit, and you'd prefer to get it done before you stop and go outside for a smoke.
If your company has recently switched to this product from a competitor's product, you may not know that the appropriate terminology for the setting you want to change on this fine product is "frabbetizing configuration". You may still be thinking in terms of the competing unit from Behemoth Inc., which calls the equivalent setting on its machine "whatsit settings".
If the manual for your new MumbleCo unit has a good index, it doesn't matter whether you know where you are in the table of contents story, and it doesn't matter whether you're up to speed on MumbleCo terminology. You can look up the term you know - "whatsit settings" - and the index teaches you, very gently, "See frabbetizing configuration." And lo, when you look up frabbetizing configuration, there it is, with sub-entries that point you to all the things you might want to know about it.
If the author of the manual has given the index short shrift, you're on your own. Maybe you should take that break before you try to find the information you need.
Fairly often, the index does get short shrift, like all the other things at the back of the book. Making a good index is labor-intensive; there's no good way to automate it, regardless of what the makers of authoring tools would like you to believe. It takes a person asking "What is this paragraph about? What would I have been looking for if my search led me here?" Fairly often, the index entry is a phrase that does not occur in the indexed material. But the fact that it may take 6 to 8 hours per page to create the index does not mean you should skip it.
The index is a reader's random-access information discovery tool, and it is (or should be) the writer's teaching tool. With all due apologies to Adobe, try this experiment: Look for a specific bit of information, using generic terminology, in the help for an Adobe product. For example, in Illustrator, how do you move a vertex to change a shape? You'll see what happens when you overlook the teaching aspect of the index. In Adobe-land, you have to know the terminology already to find the help you need. But who needs the most help? People who have no prior experience with the product, and don't know the terminology. In all fairness, Microsoft is just as bad; I never have been able to figure out if there is a way to change rows to columns and vice-versa in Excel when I decide I've structured my spreadsheet badly. And I have never been able to make heads or tails of the bookkeeping software I bought last year, because I don't know the terminology. In each case, the index fails in its teaching function - it doesn't include plain language that refers me to the specialized term.
The lack of a well-designed index in a manual or help system makes the whole product less usable.
When you work out the schedule for writing a manual or help system, include the time to create an index. In my experience, it will take about a sixth of the total writing time; your mileage may vary. But no matter how much time it takes, do it. Your readers are counting on you.
Wednesday, May 27, 2009
My job is not me
I am a technical writer.
I am a technical writer.
I am a technical writer.
That's been my mantra for many years. In the last few days I've had an experience that felt like waking up, but on a grander scale.
I'm not a technical writer.
I'm a woman with diverse interests, dreams, anxieties, strengths, weaknesses - and, oh yeah, I know how to make a living writing about high-tech gadgets. Surely I could draw a line through a different set of interests and strengths, and discover how to make a living doing something else I enjoy. But this is scary, crazy thinking. My brain freezes as soon as I realize that the logical next step is to contemplate a career change. So I stop in my tracks and meekly go back to thinking "I am a technical writer."
I'll have to change my thinking in baby steps. The first baby step is, as any good writer knows, to get rid of the passive voice. Find "I am a technical writer." Replace with "I do technical writing for a living." Ah - that creates breathing room, and the other aspects of me start reminding me that they're still here: Empty-nest mom, former Girl Scout leader, herb gardener, handweaver, swimmer, baker of uncommonly good pies. Music lover. Amateur carpenter. I don't do any of those for a living, but they are as important to me as technical writing. Getting things into focus, presenting a more balanced view - it's just a matter of thinking of myself in the active voice. My active voice.
Don't ask me how this ends. I just woke up.
I am a technical writer.
I am a technical writer.
That's been my mantra for many years. In the last few days I've had an experience that felt like waking up, but on a grander scale.
I'm not a technical writer.
I'm a woman with diverse interests, dreams, anxieties, strengths, weaknesses - and, oh yeah, I know how to make a living writing about high-tech gadgets. Surely I could draw a line through a different set of interests and strengths, and discover how to make a living doing something else I enjoy. But this is scary, crazy thinking. My brain freezes as soon as I realize that the logical next step is to contemplate a career change. So I stop in my tracks and meekly go back to thinking "I am a technical writer."
I'll have to change my thinking in baby steps. The first baby step is, as any good writer knows, to get rid of the passive voice. Find "I am a technical writer." Replace with "I do technical writing for a living." Ah - that creates breathing room, and the other aspects of me start reminding me that they're still here: Empty-nest mom, former Girl Scout leader, herb gardener, handweaver, swimmer, baker of uncommonly good pies. Music lover. Amateur carpenter. I don't do any of those for a living, but they are as important to me as technical writing. Getting things into focus, presenting a more balanced view - it's just a matter of thinking of myself in the active voice. My active voice.
Don't ask me how this ends. I just woke up.
Thursday, May 14, 2009
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.
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.
Wednesday, May 6, 2009
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.
"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.
Monday, May 4, 2009
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'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.
Wednesday, April 8, 2009
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.
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.
Sunday, April 5, 2009
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."
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."
Monday, March 16, 2009
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 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.
Thursday, March 12, 2009
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:
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.
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.
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.
Friday, February 27, 2009
Anything is possible = Nothing is possible
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.
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.
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.
Friday, January 23, 2009
Warnings that don't work
On my way home from the property tax office, I saw a road sign that made me think long and hard about what we writers do. It's a diamond-shaped sign, gold with a black border - the standard US format for free-form advisories. It says:
CAUTION: HILL BLOCKS VIEW
Why yes, so it does. Hills do that as you approach them; otherwise they'd be valleys or plains. I wondered, How much did we taxpayers fork over to have the highway department inform us of the obvious? But wait, there's more. The hill in question is neither the first nor the last on this road. It is, after all, a road through the Texas Hill Country.
Perhaps there is something special about this hill, then.
At this point my philosophical quest began to make headway.
What's special about this particular hill is not that it is, like most hills, opaque. The significant data are that it has two crests, and between them is a large church that's often used by civic organizations as a meeting-place. People driving out of the church's driveway are at significant risk of being hit at highway speed by their neighbors, or by the gravel trucks coming from the quarry just down the road. This information would not fit on a road sign, however; so we ended up with an advisory that states the root problem without giving us a clue about its all-too-common consequences.
Drivers cannot change the opaqueness of hills; but if we are aware that we are on a blind approach to a heavily trafficked driveway, we can exercise caution by slowing down and paying close attention to the road. Why, then, does the sign not say SLOW - TRAFFIC ENTERING HIGHWAY? For that matter, why did the highway department not lower the speed limit on that bit of road?
The sign is technically accurate. The hill does block the view. But out of all the information that drivers need about that bit of road, the author of the sign chose one of relative unimportance. The sign neither explains the hazard nor guides us to the correct action.
Road signs make Twitter look like Russian novels. They must be concise enough that a driver moving at highway speed can read, understand, and act upon them without being consciously distracted from the task of driving. Every word must be chosen with care. But this is not enough: Those carefully chosen words must express the right message. They must get to the heart of what is important about a road hazard.
We technical writers face the same challenge. Sometimes our readers need guidance to avoid hurting themselves, damaging the product, or losing data. In such cases, we need to tell them what consequence they need to avoid. It's not nearly as helpful to tell me that the machine may overheat if I operate it inside a cabinet as it would be to tell me that it may catch fire if I do that.
Sometimes our subject-matter experts do not make clear what the consequence of ill-advised action (or inaction) might be; in many cases, this is because they assume that anybody is able to understand the implications of the hazard. We need to ask them if they don't volunteer the information. "So, forgive me if this is a silly question; but what would happen if I put the machine in a cabinet and it overheated? Would it melt? Would it catch fire?"
Having elicited the information we need, we can wordsmith it into a form that will give our readers the information to prevent problems. That's the goal. That's always the goal when warning readers about anything. There's nothing so useless as warning people about things they can't change.
Hills have always blocked views and always will. But if we know about the hazards they hide, we can take steps to reduce the risk.
CAUTION: HILL BLOCKS VIEW
Why yes, so it does. Hills do that as you approach them; otherwise they'd be valleys or plains. I wondered, How much did we taxpayers fork over to have the highway department inform us of the obvious? But wait, there's more. The hill in question is neither the first nor the last on this road. It is, after all, a road through the Texas Hill Country.
Perhaps there is something special about this hill, then.
At this point my philosophical quest began to make headway.
What's special about this particular hill is not that it is, like most hills, opaque. The significant data are that it has two crests, and between them is a large church that's often used by civic organizations as a meeting-place. People driving out of the church's driveway are at significant risk of being hit at highway speed by their neighbors, or by the gravel trucks coming from the quarry just down the road. This information would not fit on a road sign, however; so we ended up with an advisory that states the root problem without giving us a clue about its all-too-common consequences.
Drivers cannot change the opaqueness of hills; but if we are aware that we are on a blind approach to a heavily trafficked driveway, we can exercise caution by slowing down and paying close attention to the road. Why, then, does the sign not say SLOW - TRAFFIC ENTERING HIGHWAY? For that matter, why did the highway department not lower the speed limit on that bit of road?
The sign is technically accurate. The hill does block the view. But out of all the information that drivers need about that bit of road, the author of the sign chose one of relative unimportance. The sign neither explains the hazard nor guides us to the correct action.
Road signs make Twitter look like Russian novels. They must be concise enough that a driver moving at highway speed can read, understand, and act upon them without being consciously distracted from the task of driving. Every word must be chosen with care. But this is not enough: Those carefully chosen words must express the right message. They must get to the heart of what is important about a road hazard.
We technical writers face the same challenge. Sometimes our readers need guidance to avoid hurting themselves, damaging the product, or losing data. In such cases, we need to tell them what consequence they need to avoid. It's not nearly as helpful to tell me that the machine may overheat if I operate it inside a cabinet as it would be to tell me that it may catch fire if I do that.
Sometimes our subject-matter experts do not make clear what the consequence of ill-advised action (or inaction) might be; in many cases, this is because they assume that anybody is able to understand the implications of the hazard. We need to ask them if they don't volunteer the information. "So, forgive me if this is a silly question; but what would happen if I put the machine in a cabinet and it overheated? Would it melt? Would it catch fire?"
Having elicited the information we need, we can wordsmith it into a form that will give our readers the information to prevent problems. That's the goal. That's always the goal when warning readers about anything. There's nothing so useless as warning people about things they can't change.
Hills have always blocked views and always will. But if we know about the hazards they hide, we can take steps to reduce the risk.
Friday, January 16, 2009
Adequate vs. award-winning
When I accepted a job with my most recent corporate employer, I promised the company's three founders that I would deliver award-winning documentation for their products. Then I delivered - three awards so far, with another one possible this summer.
Thinking about this last night, I asked myself: What makes the difference between an adequate manual and an award-winning manual?
The answer is the same as it would be if we were talking about cars, houses, cleaning services, wedding cakes, shoes, massages, or anything else that people do or make for other people: attention to detail. Doing all those bothersome little things that take time and effort but don't individually make much difference - because in the aggregate, all those bothersome little things make a very noticeable difference. For example, it takes time - minutes or hours, depending on the material - to make sure all your chapter or book titles and section or topic headings are grammatically parallel; but when you've done that, the table of contents reads well. Still, it's a bothersome little task that people often skip. By itself, this won't vault your good manual into the winner's circle, but if you do it along with all the other "detailing" that's involved in polishing a document before publishing it, you'll end up with a much better document.
If you want to deliver a superior product, start with a good product and a list of all the bothersome little things that people often skip in the name of holding to the schedule or keeping costs down. Then nail every item on that list. That's how you go from good to great.
Thinking about this last night, I asked myself: What makes the difference between an adequate manual and an award-winning manual?
The answer is the same as it would be if we were talking about cars, houses, cleaning services, wedding cakes, shoes, massages, or anything else that people do or make for other people: attention to detail. Doing all those bothersome little things that take time and effort but don't individually make much difference - because in the aggregate, all those bothersome little things make a very noticeable difference. For example, it takes time - minutes or hours, depending on the material - to make sure all your chapter or book titles and section or topic headings are grammatically parallel; but when you've done that, the table of contents reads well. Still, it's a bothersome little task that people often skip. By itself, this won't vault your good manual into the winner's circle, but if you do it along with all the other "detailing" that's involved in polishing a document before publishing it, you'll end up with a much better document.
If you want to deliver a superior product, start with a good product and a list of all the bothersome little things that people often skip in the name of holding to the schedule or keeping costs down. Then nail every item on that list. That's how you go from good to great.
Friday, January 9, 2009
Recipes, assumed knowledge, and indexes as teaching tools
Consider: Recipes and cookbooks are one of the oldest forms of technical writing. They tell you how to complete specific tasks, and what results to expect. Cookbooks also have explanatory material to help you understand the techniques and terminology in the recipes, along with conceptual information - why you knead bread but handle pie crust dough as little as possible, which ingredients can be substituted for others.
When my Grandma Mulholland passed away years ago, I inherited her recipe box - and realized that we technical communicators can learn a lot from trying to follow old recipes. Grandma's fudge recipe (transcribed here exactly as my grade-school educated Grandma wrote it) provides some examples.
Quick Fudge
2 1/4 C Sugar
1/2 Cube butter
1 small can Carnation milk = 2/3 cup
Boil 5 minute stir constantly
Remove from heat, add 1 1/2 C Mineture Marsh mellow and 1 Pkg of Choc Chipps - 1 t flavoring
Beat untill all disolved. Add 1 C Nut Meats & stir them in
drop by spoonfull on Wax Paper...buttered dish - cut when cool
Grandma made a lot of assumptions about what people know and what they can buy at the grocery store. Fortunately I could remember what was available in the average grocery store in a smallish city in Indiana back when the world was a large place and other parts of it were far, far away, so I was able to figure out what this all meant.
The 2 1/4 C sugar was pretty straightforward; it meant granulated white cane sugar, the default choice of sweetener in the midwestern USA during the middle of the 20th century. If Grandma had meant brown cane sugar, she would have said so - and she never encountered any other kinds of sugar.
Half a cube of butter? A bit tougher. Looking at the quantities of the other ingredients, I decided that was half a stick: 2 ounces, or 4 tablespoons.
Carnation milk would be evaporated milk. Two kinds of milk came in cans when my Grandma started using this recipe: Carnation milk, which was evaporated; and Eagle Brand milk, which was condensed and sweetened. I remain grateful that Grandma saw fit to note that a small can is 2/3 cup.
Miniature marshmallows are still with us, so that was no problem.
I had to think hard about the chocolate chips. These days I buy them in 24-oz bags, but they weren't available in such large packages when Grandma was still making fudge. I racked my brain. Grandma was not one for buying large quantities of stuff and then keeping it around. Ah - so it would be the smallest size, otherwise she would have said what size bag. So it's six ounces of chocolate chips. I used six one-ounce squares of Baker's chocolate instead, and the fudge came out right.
That brings us to "1 t flavoring" - a teaspoon of...what? Well, vanilla, again because that was the default in mid-20th century cooking in the midwestern USA. You put it in most sweets, and it was nearly mandatory in anything with chocolate.
And that cup of nutmeats - that had to be chopped walnuts. If you climbed in a time machine and went to a Kroger's or A&P in Indiana circa 1965, right beside the six-ounce bags of chocolate chips, you'd find bags of chopped walnuts. There would probably be slivered almonds as well, but they were for exotic stuff like green bean casserole. You'd never have put them in fudge. And the pecans were out of the question. Only a Southerner would put them in fudge.
So here I sit, nibbling on fudge that tastes exactly like the stuff that Grandma made every Christmas, and reflecting on how much I had to know to make that recipe turn out right.
It's making me think about what a hard time I've had learning some popular software tools, such as Adobe Illustrator and Microsoft Excel - in each case, there was a body of assumed knowledge that I did not have. In each case I had trouble using the help because I did not know the names of things. And in each case the help index failed in its teaching function - I could not look up familiar terms and get "See" or "See also" entries that pointed me to the help I needed. Sometimes I muddled through until I stumbled upon something that worked, sometimes I asked a friend, sometimes I gave up.
Well, fudge.
When my Grandma Mulholland passed away years ago, I inherited her recipe box - and realized that we technical communicators can learn a lot from trying to follow old recipes. Grandma's fudge recipe (transcribed here exactly as my grade-school educated Grandma wrote it) provides some examples.
Quick Fudge
2 1/4 C Sugar
1/2 Cube butter
1 small can Carnation milk = 2/3 cup
Boil 5 minute stir constantly
Remove from heat, add 1 1/2 C Mineture Marsh mellow and 1 Pkg of Choc Chipps - 1 t flavoring
Beat untill all disolved. Add 1 C Nut Meats & stir them in
drop by spoonfull on Wax Paper...buttered dish - cut when cool
Grandma made a lot of assumptions about what people know and what they can buy at the grocery store. Fortunately I could remember what was available in the average grocery store in a smallish city in Indiana back when the world was a large place and other parts of it were far, far away, so I was able to figure out what this all meant.
The 2 1/4 C sugar was pretty straightforward; it meant granulated white cane sugar, the default choice of sweetener in the midwestern USA during the middle of the 20th century. If Grandma had meant brown cane sugar, she would have said so - and she never encountered any other kinds of sugar.
Half a cube of butter? A bit tougher. Looking at the quantities of the other ingredients, I decided that was half a stick: 2 ounces, or 4 tablespoons.
Carnation milk would be evaporated milk. Two kinds of milk came in cans when my Grandma started using this recipe: Carnation milk, which was evaporated; and Eagle Brand milk, which was condensed and sweetened. I remain grateful that Grandma saw fit to note that a small can is 2/3 cup.
Miniature marshmallows are still with us, so that was no problem.
I had to think hard about the chocolate chips. These days I buy them in 24-oz bags, but they weren't available in such large packages when Grandma was still making fudge. I racked my brain. Grandma was not one for buying large quantities of stuff and then keeping it around. Ah - so it would be the smallest size, otherwise she would have said what size bag. So it's six ounces of chocolate chips. I used six one-ounce squares of Baker's chocolate instead, and the fudge came out right.
That brings us to "1 t flavoring" - a teaspoon of...what? Well, vanilla, again because that was the default in mid-20th century cooking in the midwestern USA. You put it in most sweets, and it was nearly mandatory in anything with chocolate.
And that cup of nutmeats - that had to be chopped walnuts. If you climbed in a time machine and went to a Kroger's or A&P in Indiana circa 1965, right beside the six-ounce bags of chocolate chips, you'd find bags of chopped walnuts. There would probably be slivered almonds as well, but they were for exotic stuff like green bean casserole. You'd never have put them in fudge. And the pecans were out of the question. Only a Southerner would put them in fudge.
So here I sit, nibbling on fudge that tastes exactly like the stuff that Grandma made every Christmas, and reflecting on how much I had to know to make that recipe turn out right.
It's making me think about what a hard time I've had learning some popular software tools, such as Adobe Illustrator and Microsoft Excel - in each case, there was a body of assumed knowledge that I did not have. In each case I had trouble using the help because I did not know the names of things. And in each case the help index failed in its teaching function - I could not look up familiar terms and get "See" or "See also" entries that pointed me to the help I needed. Sometimes I muddled through until I stumbled upon something that worked, sometimes I asked a friend, sometimes I gave up.
Well, fudge.
Thursday, January 8, 2009
Why printer specifications don't match your experience
Yesterday I read a detailed, helpful, well-written review of a new printer. The author covered all the things I'd want to know about when making a purchasing decision. A lot of the article was about how the performance numbers seemed exaggerated - testing showed that the printer didn't go nearly as fast as the published specifications would indicate. The author seemed surprised at this.
Excuse me while I change hats. There's a bit of dust on my printer R&D technician hat - ah, here we go. I will neither defend nor condemn the way that manufacturers arrive at performance specifications; but at least I may be able to explain them.
You will NEVER get the advertised speed from your printer. It does not matter who manufactures it; it does not matter whether it is a home-office desktop printer or a big high-throughput monster that the installers set on steel plates to keep it from wearing holes through the carpet. It does not matter whether it is a laser printer, inkjet, or some one of those obsolete technologies such as daisy-wheel. When a printer manufacturer publishes the technical specification for a printer's speed in pages per minute, that number represents the best speed obtainable in the test lab. If the printer is listed as a 20 page per minute printer, that means that it's able to drop 20 pages per minute into the output tray if you send it a huge print job consisting of nothing but page break characters.
How does that 20 pages per minute figure relate to actual experience?
Getting a print job started takes some time; you'll see lower average print speeds on short jobs than long ones, because the set-up time isn't all that much different for different sizes of print jobs.
If you ask your printer to actually make marks on the paper before ejecting it into the output tray - as most of us do, most of the time - that will slow things down. If your representative page in a long print job is about 30% covered with text (as for a letter or pages in a manual), your printer may do 15 to 17 pages per minute. This will be lower for short print jobs - maybe under 10 pages per minute.
If you want the printer to make marks on both sides of the paper, that will slow things down more. Even counting each sheet of paper as two pages, the speed will be lower than one-sided printing because of the time it takes the paper handler to flip each sheet.
So why do printer manufacturers not give comparison numbers from real-world testing? Would it be so hard to devise standardized testing - say, files consisting of varying numbers of pages of "Lorem ipsum"?
The other number that's likely to cause people to become unhappy with their printers is the "duty cycle" - how much of the time the printer is in use. The assumptions about how often a printer is serviced and how often it is likely to break are based on this purely hypothetical number, which is usually 25%. It's natural to assume that "25% duty cycle" means it's running 25% of the time, or 42 hours per week - but duty cycle is calculated on a 40-hour work week, not a full 168-hour week. So if your printer is rated for a 25% duty cycle, that means you are overworking it if it spends more than 10 hours a week printing. You'll hear about that from your printer service representative, who will probably urge you to get a high-output printer. It's probably good advice. You may feel as though you're being asked to trade an economy car for a luxury car, but it's more a case of not riding your moped on the freeway.
Vendors and leasing companies could save themselves a lot of explaining - and save their customers a certain amount of aggravation - by explaining how the speed and duty cycle numbers are derived; but printer manufacturers could nip these problems in the bud by adding text-printing test results to their specifications, and changing the way they calculate duty cycle.
Full disclosure: As mentioned earlier, I used to be a printer R&D technician. It has been many years since I had any connection to the printer business. Buy whatever printer you want, or hire a calligrapher - it's all one to me. :-)
Excuse me while I change hats. There's a bit of dust on my printer R&D technician hat - ah, here we go. I will neither defend nor condemn the way that manufacturers arrive at performance specifications; but at least I may be able to explain them.
You will NEVER get the advertised speed from your printer. It does not matter who manufactures it; it does not matter whether it is a home-office desktop printer or a big high-throughput monster that the installers set on steel plates to keep it from wearing holes through the carpet. It does not matter whether it is a laser printer, inkjet, or some one of those obsolete technologies such as daisy-wheel. When a printer manufacturer publishes the technical specification for a printer's speed in pages per minute, that number represents the best speed obtainable in the test lab. If the printer is listed as a 20 page per minute printer, that means that it's able to drop 20 pages per minute into the output tray if you send it a huge print job consisting of nothing but page break characters.
How does that 20 pages per minute figure relate to actual experience?
Getting a print job started takes some time; you'll see lower average print speeds on short jobs than long ones, because the set-up time isn't all that much different for different sizes of print jobs.
If you ask your printer to actually make marks on the paper before ejecting it into the output tray - as most of us do, most of the time - that will slow things down. If your representative page in a long print job is about 30% covered with text (as for a letter or pages in a manual), your printer may do 15 to 17 pages per minute. This will be lower for short print jobs - maybe under 10 pages per minute.
If you want the printer to make marks on both sides of the paper, that will slow things down more. Even counting each sheet of paper as two pages, the speed will be lower than one-sided printing because of the time it takes the paper handler to flip each sheet.
So why do printer manufacturers not give comparison numbers from real-world testing? Would it be so hard to devise standardized testing - say, files consisting of varying numbers of pages of "Lorem ipsum"?
The other number that's likely to cause people to become unhappy with their printers is the "duty cycle" - how much of the time the printer is in use. The assumptions about how often a printer is serviced and how often it is likely to break are based on this purely hypothetical number, which is usually 25%. It's natural to assume that "25% duty cycle" means it's running 25% of the time, or 42 hours per week - but duty cycle is calculated on a 40-hour work week, not a full 168-hour week. So if your printer is rated for a 25% duty cycle, that means you are overworking it if it spends more than 10 hours a week printing. You'll hear about that from your printer service representative, who will probably urge you to get a high-output printer. It's probably good advice. You may feel as though you're being asked to trade an economy car for a luxury car, but it's more a case of not riding your moped on the freeway.
Vendors and leasing companies could save themselves a lot of explaining - and save their customers a certain amount of aggravation - by explaining how the speed and duty cycle numbers are derived; but printer manufacturers could nip these problems in the bud by adding text-printing test results to their specifications, and changing the way they calculate duty cycle.
Full disclosure: As mentioned earlier, I used to be a printer R&D technician. It has been many years since I had any connection to the printer business. Buy whatever printer you want, or hire a calligrapher - it's all one to me. :-)
Saturday, January 3, 2009
It can't be that hard
When did you last buy a new techno-toy...
...look at the manual...
...carefully put away (or carelessly throw away) the manual...
...and say "I'll work it out on my own"?
When did you last get stuck trying to figure out a new techno-toy on your own...
...heave a deep sigh...
...and consult the manual - only to find that it made you feel as though your head might explode?
Is it just me, or does the average manual make things sound hard?
It's a new year. It's a good time for a new view of things. Try this on for size: Nothing is as hard as it sounds when your subject-matter experts tell you about it. Nothing. Because inside every arcane, elegant, hackish implementation that takes half an hour to explain is a beautifully simple idea. As technical communicators, it's our job to listen for the faint, pure song of that simple idea. It's our job to tune out the cacophonous techno-babble that normally drowns it, and let the music of that simple idea be heard loud and clear.
Sometimes we get push-back from our subject-matter experts if we strip away the tech talk - particularly if they have taken the trouble to write explanations for us. (This, by the way, is as good an argument as any for never asking your subject-matter experts to write anything for you.) But I've found that I can win over even a fussy subject-matter expert by explaining that I am trying to showcase the brilliance of the design, and that customers will see it more clearly if it's in layman's terms. True brilliance in product design is in implementing a simple idea and concealing the complexity of the implementation. The people at Apple know this, and it's made the company a huge success.
It's not just Apple. There's a lot of talk about Web 2.0 being all about user-generated content, but what makes that possible is the true core of Web 2.0: If it's hard, nobody will use it. Everything is easy.
Hard to use, hard to read, hard to understand - we're done with that. Everything is easy.
How does your product documentation look? Find the essential simplicity and take out the rest.
...look at the manual...
...carefully put away (or carelessly throw away) the manual...
...and say "I'll work it out on my own"?
When did you last get stuck trying to figure out a new techno-toy on your own...
...heave a deep sigh...
...and consult the manual - only to find that it made you feel as though your head might explode?
Is it just me, or does the average manual make things sound hard?
It's a new year. It's a good time for a new view of things. Try this on for size: Nothing is as hard as it sounds when your subject-matter experts tell you about it. Nothing. Because inside every arcane, elegant, hackish implementation that takes half an hour to explain is a beautifully simple idea. As technical communicators, it's our job to listen for the faint, pure song of that simple idea. It's our job to tune out the cacophonous techno-babble that normally drowns it, and let the music of that simple idea be heard loud and clear.
Sometimes we get push-back from our subject-matter experts if we strip away the tech talk - particularly if they have taken the trouble to write explanations for us. (This, by the way, is as good an argument as any for never asking your subject-matter experts to write anything for you.) But I've found that I can win over even a fussy subject-matter expert by explaining that I am trying to showcase the brilliance of the design, and that customers will see it more clearly if it's in layman's terms. True brilliance in product design is in implementing a simple idea and concealing the complexity of the implementation. The people at Apple know this, and it's made the company a huge success.
It's not just Apple. There's a lot of talk about Web 2.0 being all about user-generated content, but what makes that possible is the true core of Web 2.0: If it's hard, nobody will use it. Everything is easy.
Hard to use, hard to read, hard to understand - we're done with that. Everything is easy.
How does your product documentation look? Find the essential simplicity and take out the rest.
Subscribe to:
Posts (Atom)
Posts
.jpg)