Posted in Advice

Making Word Templates Work

Word can be a bear to work with. People complain all the time about its glitches, gizmos, and other time-consuming peculiarities. So I had this thought as I worked to develop a template for PDFs to be read online. Why don’t I try to do a template that not only maximizes online readability, but also gets around Word’s problems? I wanted to work with a template that was so easy to use, Word wouldn’t have a chance to screw up the template or the document. The project worked, and I don’t dread working with Word anymore. Now it’s another tool that you can actually use to be productive.

The beginning of my story is suggested in the first paragraph above: my desire to develop a template so simple to use and maintain that Word couldn’t screw it up. It turns out that a template like that also produces easy to read documents.

The boundary line between print and online publications has become pretty fuzzy. Writers recognize that the same ore similar templates can be used for both. PDFs, for example, are intended for both online and print publication, so templates intended for PDF documents cross the boundary at conception. It’s true that a lot of PDF documents are headed primarily for one or the other, but that shouldn’t trouble us.

I keep saying to myself that this is not a sexy topic, but everyone recognizes how important templates are. The other day I found myself comparing the templates we use to an oil refinery. The crude oil that goes into a refinery is thick, sludgy, and unusable by anyone. Out the other end comes a much refined product called gasoline that everyone finds extremely useful. Templates are the same way. So many companies have all this disorganized material around that’s not so useful to anyone. You look at it on the page and your interest in finding valuable information there withers. We use templates to refine crude information that no one can use. With the proper tools built into the template, we can refine the information and make it inviting. People like to search it because they can get answers quickly.

So I don’t think it’s that productive to dwell overmuch on the online vs. print distinction. I’ve considered whether I should say much about the template I use in RoboHelp when I’m doing a help system, as opposed to the Word template that started these thoughts. But it just doesn’t seem that important to me whether the destination document is paper, PDF, or HTML. Yes, those destinations are different, but a lot of the principles regarding good templates are the same. That is, we should think about what makes a template good in various contexts. The comparisons are helpful, and you, I expect, will have a lot to say about those comparisons as you think about your own work.

Posted in Uncategorized

Delegate Wisely

I seldom watch television news, but I like to read about what happens there. So I learned of Michael Brown, former head of the Federal Emergency Management Agency, and his unfortunate reply when someone from CNN asked him about the situation at the New Orleans convention center. He didn’t know anything about it, even though the networks had highlighted the dire situation at the center for about twenty-four hours.

Well I wouldn’t expect the director of FEMA to watch CNN during a crisis like that. If he’s taking time to watch television, he’s definitely not doing his job. If his organization’s running well, he has an assistant who gives him the information he needs before he updates the nation on his agency’s response to the hurricane. If the information’s not available, the assistant reminds him: “And sir, if they ask you something you don’t know, tell them we’re doing everything we can, as fast as we can.”

Clearly FEMA was not a well-run organization, and Mike Brown did not have an assistant to remind him what to say. Management experts will analyze the breakdown at FEMA for a long time, but we can say now that Michael Brown didn’t delegate wisely. From what we can see, he didn’t delegate key tasks at all. A breakdown follows, because one person can’t do everything. We know that an organization without wise delegation can’t function well.

Effective delegation of responsibility works much the same in most settings. Let’s switch our view to a business enterprise. Think about instances of effective and ineffective delegation in your own workplace. What do you (and others) do when you delegate wisely? What do you avoid? Here are three initial points:

~ Work with people you trust.

~ Listen carefully to what they say.

~ Involve yourself with the work they do.

Trust

Let me make a few remarks about working with people you trust. I don’t have anything new here, just reminders of what we already know:

~ Keep your word.

~ Expect honesty and openness from the people who work for you.

~ Keep lines of communication open and active.

~ Expect great things, but also give people room to make mistakes.

~ Ask for help when you need it, and expect others to do the same.

In all of these principles, you make yourself and those you work with worthy of trust. People who trust each other can get a lot done together.

Listen

Listening is your main communication tool if you want to stay in touch with what is happening right now. If you listen carefully to people’s reports, you’ll hear problems, proposals, and important information that you need to know.

The manager’s everyday questions are: What do you need from me? How can I make your job easier? What can I do to make you more productive? In a good working relationship, where communication comes easily and the manager is in touch, the manager won’t even have to ask these questions. The responsible person knows what the manager needs to know, raises current issues, and the conversation begins.

The first quality of a good leader is to be a good listener. Of all the communication skills, it is probably the most difficult. It requires at least as much discipline and concentration as writing. You have to engage with the speaker and be ready to respond. Good listeners demand a lot of themselves.

Let’s compare listening and reading as information gathering tools for a moment. You can ask people to put everything in written reports, but how timely is the weekly status report? A detailed report takes time to write, and people don’t like to put bad news or troublesome problems in writing. To get a detailed and realistic picture of what’s happening right now, you need to talk to people.

Here are a few practical points you can use in any work setting:

~ Create opportunities for listening. Informal, short meetings and one-on-one conversations give people a chance to talk.

~ Ask questions about what’s going on, and mean it. People love to talk about the work they are doing. Genuine interest is rare, and people respond to it.

~ Ask good follow-up questions. That affirms your interest, confirms you’ve been listening well, and encourages the speaker to expand on important issues.

~ Listen for problems and issues that require coordination. That’s where you can make people’s jobs easier: when you coordinate their work flow with others’ work flow.

The great thing is that when you give yourself over to these activities, you benefit from being generous to others. So, when you’re a leader, take time to listen to what others have to say. The people who work for you want to make you look good, but they can’t do it if you close them out. Interestingly, you let them in when they talk. And after you have invited them in and listened to them, they’ll listen to you and work hard for you down the line.

Engage

I know a school director who trains and supervises teachers. She visits the teachers’ classes regularly. The teachers appreciate the chance to talk with her about how the class is going. Yes, she goes to make sure things are going okay, but the teachers don’t feel she’s looking over their shoulders. She offers some on-the-job training, stays in touch, finds out what they need to make the classes go better.

It’s the same with writing. A writer works alone during much of the book development process. So a writer always wants a good editor at the end. The editorial process is built into book development, not because editors think writers won’t get it right, but because it is the best way to complete a project. The publication improves when writer and editor communicate well, when they collaborate to create the best possible book for the customer.

In both cases – classroom teaching and publishing – supervisors engage themselves in ongoing work. We all know about the manager in Dilbert: he’s out of touch and slows things up at every turn. A good leader knows what’s needed and offers a welcome assist. With good management, a collaborative model of leadership is built into the process of delegation.

To Conclude

The consequences of not delegating wisely can be pretty bad. People die unnecessarily in the aftermath of a hurricane. A corporation goes bankrupt because no one but the perpetrators knew about the financial chicanery going on. An army loses its fighting effectiveness because its leaders don’t listen to the soldiers and officers in the field.

Closer to our workaday experiences, we know that poor delegation has a lot of smaller effects. Schedules slip or don’t get written to begin with, bottlenecks develop, strained working relationships cause low morale. All of these affect productivity. When productivity goes south, call a holiday – and the management consultants!

The odd thing about delegation is that it happens all the time, in the messy world of everyday work. It’s informal. Lines of authority change. Friendships go through good and bad times. Projects change, some things get done and others don’t. In the midst of a confusing environment with subtle signals, it’s useful to stay with some simple principles that hold in all settings: work with people you trust, listen carefully to what they say, involve yourself with the work they do. All three of these principles point toward healthy and productive working relationships. And within that kind of relationship, wise delegation comes naturally.

Posted in Advice

Simple Planning Tools for Project Estimation

When you plan a hike, you can make distance or time your primary planning tool. Let’s say you want to go 5 miles. The area is rugged and unfamiliar, you’re not sure about the weather but it’ll probably be hot, and you want to stop to rest at scenic overlooks. You estimate the trip will take about three hours, with an extra 45 minutes for lunch. Alternately, you might think: “I have 3 hours for this trip. How far can I go in that time?” Again you consider distance, terrain, weather, and rest stops. You conclude that if you keep lunch fairly short, you can cover just under 5 miles.

The same reasoning processes can help you estimate a project accurately. How much can I accomplish in the time that I have available? How much time do I need to accomplish these tasks? If time rules, then you have a fixed deadline and you make judgments about what you can accomplish before that point. If the document rules, then you adjust the project schedule to reflect the time that you need to complete the various phases of the project. In many cases, neither the deadline nor the document rules completely, and you have to balance the requirements of both.

If you have to complete a 100-page document in two months, for example, and you know you cannot devote full time to it, your planning has to balance chunks of the publication against chunks of time. What can I produce in two months? How much time do I need to produce what the customer says she needs? If you ask both questions at each of your planning sessions, then you can set a realistic schedule and reach the end of the project with a document that meets your customer’s expectations.

A half-day hike requires some simple estimates about time and distance. A long publication requires a more protracted and complex planning process, but the analytical methods are essentially the same. For a document, you can do one of the following:

  • Start with the project completion date and use that benchmark to plan the scope of the publication.
  • Start with the requirements of the publication and set the project schedule based on the time needed to meet the requirements.

Typically, you need to use both methods to develop a sound plan.

Posted in Advice

How to Assemble the People You Need for Your Doc Project

When you need to produce a technical document, you can rely on three types of resources. You can employ in-house staff, hire temporary staff through a contracting agency, or hire the services of a technical publishing firm. Let’s compare these three options as to cost, quality, and control.

Cost

From the standpoint of price, in-house staff are an attractive option. They are already on the payroll, and they already have much of the training they’ll need. Outsourcing the job requires adding a substantial chunk of money to your budget request. The budget item is visible and has to be justified, whereas assigning the job to people already on board is invisible to the manager who oversees the budget. If the people who take on the publication were hired for that kind of project, or were idle anyway, the company has made good use of its resources.

On the other side, a major writing project won’t boost the morale of engineers or other staff who don’t see documentation as part of what they were hired to do. If writing forces them to neglect other important work where they feel their talents are well used, the hidden cost to the company can be rather high. Outsourcing the project in that case can make the final stages of product development more efficient and less aggravating.

Quality

When your company decides to produce a document, it’s usually pretty late in the product development cycle. The customer wants something written when the product ships, and they won’t be happy if the instructions are missing. How can you produce a high quality technical document – one that serves your customers well – on a tight deadline? This section looks at the question of resources with the tradeoff between time and quality in mind.

Some managers look to agencies to help them assemble the resources they need on short notice. Agencies can send them candidates with the right skills, quickly. Later on they look at the quality of the talent they hired and wonder if they didn’t pay too much.

The problem isn’t that agency writers can’t produce high quality material. Many writers have worked with agencies, and they have found plenty of talent among their colleagues there. The quality problem arises because the agencies themselves use a meat-market model to place their offerings. They, too, are concerned with time. As a result, they generally don’t know whether they’ve sent ground beef to McDonald’s and their best filet to the Ritz, or the other way around.

How does this question look from the perspective of the project manager? Even if an agency looks attractive in the short term, the decision to hire staff there can cost time and money over the course of a project. The agency solves the immediate hiring problem, but this source of talent returns unreliable quality for a relatively high price. Why? At least three reasons exist:

• Contracting agencies must place many candidates every month to make a profit. They cannot take time to learn much about their customers’ requirements or technologies. That’s why they depend so heavily on clients’ job descriptions and candidates’ resumes to make a match.

• Resumes are a poor way for anyone to match job requirements to job skills. Because agencies treat job skills as a commodity – Does the candidate know RoboHelp? FrameMaker? – they don’t know whether the person they’ve supplied will actually serve their customer well.

• Project managers urgently want someone who fills their need now. Agencies respond with the best person they can find at the moment. They know their customers do not have the time or the inclination to break off the relationship and look elsewhere for their talent. At worst, the agency can supply one ill-suited candidate after another until they get it right.

Of course contracting agencies are here to stay. They serve some useful purposes for both writers and managers, and they’ve become well-established in our trade. Most of all, they serve as a good backup when time is short. Yet both writers and project managers can easily let procrastination become a bad habit. If writers procrastinate in their marketing efforts and managers procrastinate in their hiring, agencies become a routine fallback option. With foresight and plenty of direct contact, writers and project managers can develop solid business relations that result in high quality work and less wasted time.

Control

Project managers may feel most comfortable if the work they supervise is conducted in-house. That makes for smooth and generally uninterrupted communication. Guidance, feedback, trouble reports, plans, work schedules, and inter-departmental notices can all flow back and forth seamlessly when writers and editors work on the premises. In addition, on-site work gives writers and editors direct access to the company’s network, and helps avoid the version control problems that can arise when work is conducted off-site.
In light of all these advantages, one might want to know why a project manager would ever want to supervise work conducted off-site. Here are several reasons:

• Off-site workers supply and maintain their own hardware, software, and office space. The hiring company does not need to expend its own resources to support the publication effort.

• Off-site workers can be more productive from day to day because they don’t have to deal with long commutes and heavy traffic.

• Perhaps most important, responsibility for project management sits more squarely with the off-site worker. As off-site workers supervise themselves, they relieve project managers of the burden of daily oversight. Instead managers review results at key points in the project.

Many projects, of course, include a combination of on-site and off-site work. Often a great deal of on-site time is required during the research phase at the beginning of a project, and during the publication phase at the end. The document development phase in the middle can be conducted on- or off-site. Writers and project managers can discuss what arrangements work best in advance.

Summary

Here are some conclusions we can draw from our analysis:

• When money is plentiful, time is short, and the publishing task is relatively simple, a contractor from an agency can be a safe and efficient choice.

• If your company has a staff of well trained writers, editors, illustrators, and desktop publishers, use them. Many specialists in technical communications can develop skills in all four areas. Then the only reason to go outside for help is when the volume of work clearly exceeds the time available to accomplish it.

You should hire a technical publishing firm to complete your project if the following conditions hold:

• You want to pay a fixed fee for your project rather than an hourly rate on an indeterminate amount of time.

• You lack specialists for complex and labor intensive publishing tasks, and you want to keep your engineers focused on their design work.

• You trust your vendors to deliver what you want, at the stated price, on time. If you have that kind of relationship with a publishing firm, you can purchase good quality, and be confident you have spent your resources well.

Posted in Advice

How to Conduct Interviews for Serious Research

Talking with people is a good way to gather information. It’s efficient and fun. Interviewing techniques used to conduct research may seem difficult to master, but an interview is just a special kind of conversation. A successful job interview, for example, is one that most resembles a normal exchange of ideas between two people. Journalists conduct interviews all the time, and for the most part they learn how to do it on the job. For others, what happens before, during, and after an interview can seem unfamiliar. This short article tries to demystify the interview process and to help researchers use interviews to good advantage in their work.

Conducting an interview is much like talking with someone about, say, real estate values, flying an airplane, or starting a business. In a couple of key respects, though, an interview is not like an everyday conversation. One difference is that the exchange focuses on a related set of ideas or problems for a longer period of time than is the case with most conversations. Another difference is that researchers plan to put what they have learned in written form after the conversation is finished. Together, these differences mean that a successful interview requires good planning and good follow-up.

An inexperienced interviewer’s instinct is to write up a list of questions ahead of time. Then during the interview, the researcher ticks off the queries: “How was…?” The other person answers. “What do…?” The person answers again. “Why did…?” The structured back-and-forth exchange continues. That’s not a terrible way to conduct an interview: it’s better than coming in entirely unprepared. Still, it doesn’t give very good results. The interviewee will probably check his or her mental clock on the wall about five minutes into the exchange. Even more importantly, the researcher misses the chance to conduct a conversation that ranges beyond the limits defined by the original list of questions. Whole fields of useful information – not just stray bits here and there – go untouched as a result. So, here are some tips for conducting an interview that’s worthwhile for both participants:

• Write ample notes to prepare. Think about what you’d like to know. Think about what you already know, and how you can connect that knowledge to what you’d like to find out. Write down questions in your notes, but make them general and don’t worry if they are ill-formed. Also, be self-centered at this point. Focus on what you’d like to find out. The center of attention will shift more toward what the interviewee knows once the conversation starts.

• Communicate with your resource in advance. Get in touch ahead of time not only to set up the appointment, but also to let the person know what the interview will be about. That lets the person think about the subject a bit before you arrive. If you can, send an e-mail that outlines in general terms what you’d like to talk about during the meeting.

• Review your notes. If you write your notes shortly before the meeting, you may have time to review them only as you walk down a hallway or while you wait for the interviewee to take a phone call. That’s often all it takes. The main thing is to keep the contents of the notes fresh in your mind.

• Conduct the interview. Engage the person in an informal exchange. Listen carefully, and respond to what the other person says. Refer to your notes when you need to, but rely on your memory, too. Be willing to jump around – you don’t have to follow a set order in your questions. A good conversation doesn’t lend itself to that much structure anyway. Practiced interviewers learn that their best information comes in response to questions that didn’t occur to them as they prepared for the meeting. Ask follow-up questions, even if that means you have less time to cover ground you mapped out in advance. Good conversations are lively, like a dance of sorts, and that’s no time to be rigid.

• Check what you have learned. Ask questions designed to confirm what the other person has said. For important or complex points, summarize what you’ve heard and ask the other person to tell you whether you have it right. You want to communicate this information to your audience in writing and you need to know it well. Feeding the information back to the other person in your words cements your own understanding. It also gives the other person an opportunity to expand or qualify arguments, fill in gaps, correct errors, clarify ambiguous points, explain or modify controversial statements, and the like.

• Express your appreciation. The other person has given not only time, but has tried in the midst of a busy schedule to gather some important thoughts together for you. If you have developed some rapport with the person along the way, leave open the possibility of a phone call or other communication down the line. Follow up with an informal note of thanks via e-mail. You’ll appreciate the opportunity to confirm or clarify as you get further into your writing. So will the other person.

• Write up your meeting notes soon after the interview. Some people tape record interviews so nothing is lost. You’ll also have any notes you and your resource write during the session. The most valuable record of the interview, though, will be the detailed notes you write afterwards. They’re valuable because you can use them as a foundation (or a partial foundation) for the written product you are working on. Try if you can to write the notes no more than twenty-four or forty-eight hours after the interview. If you want to capture all the atmosphere and nuances of the conversation, write them within an hour or two after the talk. If a busy schedule doesn’t allow that, write them even if three or four days have passed. Do it even if you think you have forgotten most of what you talked about—your memory can retain things for a long time. Review the materials you have in your meeting file to put your memory in active mode.

• Type your post-meeting notes. Make the passage from rough notes to rough draft painless. After you organize your notes and put them into sentences and paragraphs, and after you integrate them with other material you have gathered, you’ll have something that starts to look presentable. Marking up notes is much easier – and more fun – than trying to write well-formed sentences on a blank sheet of paper or a blank computer screen. Moreover, you’ll reach your goal of a draft that others can review much more quickly than you thought possible.

These are basic steps of effective research conducted away from the library and internet. Let me offer one caution, though. Don’t treat these ideas and suggestions as step-by-step instructions. Compare what I’ve learned from my research and adapt it to your own work habits. Remember too that you’ll need to adapt your research techniques to the particular project or field you’re engaged in, whether it is historical, technical, financial, medical, scientific, political, or some other area. For some subject matter, talking with people is the only method of research available. For other projects, interviewing complements other research techniques. Either way, practice your interviewing skills and become adept with them. Make them part of your toolkit as a researcher and writer.

Posted in Advice

Curse of Low Expectations

In a lot of situations, you can benefit if other people underestimate you. If you can get your opponent in a chess game or a tennis match to be over-confident, you can be a tortoise to your opponent’s hare. If people have low expectations of a candidate going into a presidential debate, it’s easier to come out looking like a winner. That’s what the campaign aides suggest, anyway. We know we try to calibrate expectations on the job all the time, regarding what we’re able to do by a certain deadline. We want expectations to be low enough that we can exceed them without killing ourselves, high enough to maintain a general aura of confidence and respect. No one wants to be thought incompetent!

So why are low expectations a curse, if we stand to benefit when they’re on the low side? The curse develops if we let them affect our own self-image. I read an article in the Intercom a while back. I don’t remember much about the subject matter of the piece, but one statement confronted my brain and stayed there. The author said that technical writers can’t ever know as much about the systems they document as the engineers who design the systems. Well, that’s true enough. The disturbing thing was the author’s extended premise that writers are so knowledge-poor that they depend almost entirely on engineers for their content. That section of the article might have been titled, How to Manage the Spoon Feeding Process.

When I read that part, I thought man, that’s just what bothers me about our trade. We don’t feel like we can do anything without subject matter experts, or SMEs. The first time I heard that term, it repelled me right away. Sure engineers are smart and they know a lot, but I can’t think they like being called SMEs. We shouldn’t adopt the term, either. Engineers are colleagues, people we collaborate with to create useful products. If you think of your collaborator as an SME, you’ll never feel like an equal. You’ll just return from the engineering division to the doc department, the ghetto of the non-experts.

So how do we exorcise this curse, given the benefits we can realize when engineers don’t expect too much from us in the way of technical knowledge? A psychological remedy is to keep other people’s beliefs from affecting our own beliefs. If engineers don’t expect much technical expertise on our part, we don’t have to lament their occasional condescension. Let them think what they like. The difficulty lies in lamenting their belief and believing that they’re right. A degree of dependence becomes total dependence.

Here are some practical ways to escape the dependent state of mind:

~ Make stuff up. Yes, you read that correctly. I was working on a pretty tight schedule in an area that was new to me, and my document still had a lot of information missing. When I told the project manager that my technical contacts weren’t returning my calls, he told me to make things up. I told him I couldn’t do that. He said sure you can. So I tried making some educated guesses and plugging them in. It turned out that my guesses were pretty close, and the people who knew the answers to my questions could easily correct my inaccuracies once they saw the material written down. As we all learn so often, we know more than we think we know.

~ Treat your engineering colleagues as equals. Don’t over-estimate their knowledge and skills. Then you become, in your eyes, a high-tech stenographer waiting to take dictation on matters that are largely beyond your comprehension. Treat collaborators as you would like them to treat you, and you’ll find that you treat yourself better as well.

~ Be as active as you can in seeking new knowledge. I know from long experience that it’s difficult to find time to do much of that. Building up technical knowledge about the systems you work with, though, is a sure source of job satisfaction. Yes, we can claim a lot of expertise in the tools of the trade, and that’s a source of some satisfaction, but I think the truly attractive thing about technical writing is the opportunity to learn about lots of interesting technologies, innovations and methods. We get to learn how things work.

Being active in knowledge acquisition means just what it says: read everything you can, talk with lots of people – not just SMEs, write thorough notes before and after your meetings, think about what you don’t know and how you can learn it, think about what you do know and how you can extend it. More rapidly then you expected, you’ll absorb more about your subject matter than you thought you could. Your active search and integration of new knowledge with old will make you an expert, too. Then let the SMEs think whatever they like.