One of my most enjoyable jobs ever, believe it or not, was revising a large company's hopelessly-outdated procedures manual. I say "enjoyable" only because:
a) I already knew most of the subject matter down cold
b) I had a fluid, open-ended deadline
c) Putting together 2,000-piece jigsaw puzzles appeals to me
d) My boss was so desperate to get it off her own desk that she gleefully let me write it pretty much any way I wanted.
In doing this mammoth project, I received my own practical education about the art of manual writing. So I present here my takeaways, in case you, my fellow writer, ever land a similar dumb -- er, I mean plum -- assignment. Oddly enough, these tips are organized into 12 steps -- perhaps intimating that you may be ready for another sort of 12-step program by the time you're done.
So here we go! You've been asked to write a manual! First things first...
1. Put your prize-winning author aspirations on hold. This will not be Shakespeare. In fact, a manual is the exact opposite of the Great American Novel. It is not supposed to elicit any powerful emotions. Actually, it should not inspire any feeling at all in your readers, except maybe a mild sense of bafflement mixed with apprehension, as in: "Geez, I've been doing that procedure all wrong for the last six years. I hope it doesn't come back to haunt me."
2. Grimly accept that your efforts will largely go unnoticed. The term "reference manual" is an oxymoron. People really don't refer to their manuals. They sit in plain sight on shelves or credenzas, but they only get pulled out when all other possible sources of information have been consulted and exhausted -- including old email threads, Google searches, archaic publications, water cooler grapevines, and repeated voice mails to Shirley, the office gossip who formerly dated the guy who originally designed the procedure in question back before the Y2K scare changed everything around.
3. Take whatever is provided to you as source material for your manual (if anything), and mentally draw a black line through everything in it. Only use these text snippets/photos/diagrams/images as loose guidelines for figuring out what topics are expected to fall into the project scope.
4. Find a manual whose design you like -- it can be the manual that came with your cat carrier, your clothes dryer, or your car -- and plan to copy its format shamelessly. Hey, if it worked for Ford Motor Company, it can work for you too, right? The difference is, Ford paid some people big bucks to come up with a nice design. Why reinvent the wheel? Just use theirs.
5. Having said # 4 above, let me do an instant partial retraction and say that whatever format you use, it better fit into an 8 1/2 x 11 portrait page layout, or you will get a nasty jolt when you need to price it out for printing. I'm just giving you the brutal reality here. In the same vein, your beautiful Word document will need to have fonts, margins, and image file types that are industry standard, that is, they do not burst through into new design territory. Best to have a talk with your print vendor beforehand to find out what the most cost-effective specs will be.
6. You may think that you are finally ready to start writing, but you're not. First, you need manual writer's insurance. To get it, make a list of everything "they" want you to include in the manual. Go into merciless detail. Then, send the list to your project owner via email and say "Are you sure that's all?" He will say "yes," then two months from now you will find out that he meant "no," but at least you will have his old email reply to show him when you tell him that due to the added scope of the manual you now need another X days/weeks/months to complete it.
7. Armed with your list of subject matter experts, or SMEs, the source of which is your "project owner" above, schedule a fact gathering session with each one. Take a hard copy of your relevant source material (double-spaced, if possible), or whatever other source notes you have, to each SME session. Also take along a sharp pencil. Go over each instruction with your SME and ask, "Is this still true? Is this the exact way we want them to do it? Is there anything else we need to tell them here?" etc. With your SME's guidance, make careful and legible notes on all the changes you need to make. (I underlined the "legible" part there from bitter experience.)
8. Don't start actually writing your manual until you have done all your SME sessions. This is because, once you have all the corrected procedures in hard-copy format, you might begin to see frequencies, discrepancies, redundancies, similarities, and other -ies that need fixing. For instance, in one manual that I got from someone to revise, he had started every chapter with the words "Log in to the site: Click on the portal link on the desktop. A log-in screen will appear..." After eight repetitions, it began to sound like the old folk song, I Know An Old Lady (Who Swallowed A Fly), in which each verse is a tedious repeat of all prior verses: "..she swallowed the goat to catch the dog, she swallowed the dog to catch the cat..." Needless to say, I had a lot of condensing to do before I actually even understood that manual's basic drift. So again, conclude all your SME sessions before you frame out the big picture. At some point, you do need to actually start writing, and you will be itching to begin -- but to do your manual justice, you need to organize it well. And organizing a manual's information is a lot like projecting election results. Do yourself a favor and wait, as they say, until "all reports are in."
9. Another thing to wait for is -- and this is my firm rallying cry whenever I deal with IT people -- final screen shots. In other words, don't waste your time plying through an involved system application and wrestling all of its steps onto paper, only to hear back from the developers that they have since streamlined that particular function and now it's only two clicks. It's okay to get an approximate feel for procedures or applications from preliminary outlines, pilot Visio graphics, or "sandbox" sites -- but do NOT fill in all your blanks until they've filled in all of theirs. Otherwise, you will be Finding and Replacing ad nauseum. Instead, keep a list of things that are still "TBD" and leave those manual sections entirely blank. Report back to your project owner when you are getting stonewalled. Listen, it may be their manual, but it's your reputation if you get something wrong because of some new change they forgot to tell you about -- so hold your sources accountable, and send out emails (which you will save for posterity) if your questions go unanswered and endanger your timeline. (This is a variation of the principle in step #6 above about scope changes and manual writer's insurance.)
10. Okay, now you have all your final correct, pristine, expert-certified material. Go ahead and put it all in order now, mimicking the beautiful (see step 4 above) manual you have chosen for inspiration. Write everything down in sequence -- then gut it. That is, go back through every page and delete every non-essential word to make your manual as lean and mean as possible. This is to make it as usable as possible, in case anyone ever really does decide to use it. Remember: No persuasive opinions -- no subtle shades of meaning -- no congratulatory asides. Peppy comments like "You've finished your physical inventory! Good job!" are why so many manuals get accidentally tossed into incinerators.
11. Done putting together your full draft? Ri-i-i-i-ight. Now send your "finished" manual back to your SMEs for review. Also ask your project owner for the names of any other entities that need to get a gander at your spanking-new procedures, and send it to those guys as well. Because lawyers, HR directors, controllers, auditors, janitors, various vice presidents, and Shirley the office gossip may all need to weigh in, too. Not a problem! Shoot that manual draft out to anyone who needs to review it -- but be sure to include this all-important sentence in your cover letter: "If we do not hear back from you by [such-and-such a date] we will assume that you have no changes and we will proceed to finalize and go to print." That should get their attention. Or their inattention. Either way, your relentless march toward your release date is safe and on track.
12. When you've gotten your reviewers' changes back (or not) and added them in (or not), it's time for final polishing. For this step, I earnestly say: if you're not an expert in Microsoft Word, especially its Style and Page Numbering functions, try to pawn off this final formatting to someone who is. If you can't, schedule an extra week or two to wrestle with your manual's headers, footers, section breaks, hyperlinks, book marks, Table of Contents, and especially (shudder!) its Index. Do some internet sleuthing to get some cheat sheets and insider tips about Word's Tweety-Pie-on-the-outside, Tasmanian-Devil-on-the-inside formatting "aids." These are components that used to be done by whole armies of guys in the old days of publishing, but now are done by, well, you. Sorry, I would insert my own tips for these functions here, but by the time you read this, they may already be out of date.
Which brings me to my final words of wisdom: after you've created your Master Official Final Final Version of your manual, stored it on a hard drive somewhere, and sent a copy off to the printer with your order for umpteen thousand copies, expect a phone call the very next day. It will go something like this: "We have revamped the entire [whatever] procedure. When can we meet to discuss changes for the manual?"
So much for your manual labor. Sisyphean in nature (hey, there's a Google search for you!), it is nonetheless a rewarding challenge for the rare pleasure that results when you meet a target user who says, "You wrote that manual? Thank you! It's saved me on so many occasions!"
That's where the last of the 2,000 puzzle pieces falls into place, and we manual writers tilt our heads modestly, smile, and revel in the admiration of our under-appreciated artistry.
Right before we head out to our 12-step meeting.
No comments:
Post a Comment