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.
Friday, January 23, 2009
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)