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.
Thursday, July 30, 2009
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.
Subscribe to:
Posts (Atom)
Posts
.jpg)