Category: Uncategorized

What Technical Communicators Can Learn from the Airline Industry

The higher the risk, the more you need good documentation. In perhaps no industry is this more true than in the airline industry.

Early on in the industry, pilots were held to be remarkably smart people. Part of the aura of a pilot was that they were expected to be able to hold any needed flying or plane maintenance procedures in their heads.This tradition grew up as a result of the example of the first pilots. The Wright Brothers performed extensive checks on their aircraft, and were intimately familiar with all aspects of their equipment. However, the Wrights’ machines were comparatively simple. As aircraft grew more and more complex, pilots were expected to store and execute more and more, and increasingly complex, procedures. 

That all changed in 1935. Two pilots for an important Boeing Model 299 test flight neglected to check one piece of equipment. Essentially, they forgot to check a single box in their mental checklist. This resulted in the malfunction of a key control mechanism, and a fiery crash.

In the wake of the crash, the industry realized that expecting pilots to remember many complex procedures was asking for trouble. The stakes were just too high.

Airlines, and the Air Force, developed detailed, written checklists for a variety of piloting and maintenance tasks. These checklists reduced risks by ensuring that pilots’ memories were not overtaxed. As Air Force Magazine points out, a checklist is an “informational job aid used to reduce failure by compensating for potential limits of human memory and attention.”

Moviegoers were treated to a great example of these checklists (collected in a QRH, or Quick Reference Handbook) in the 2016 movie Sully, which detailed the miraculous landing of an Airbus A320 on the Hudson River. As you can see in the video here (starting at 17:30), the two pilots of the failing craft carefully consulted the book of procedures in landing their craft safely in the water.

Checklists (and other documentation) are chiefly useful when a situation isn’t optimal. When equipment malfunctions in an unusual way, when you have a new person in a role, or when risk is high, documentation becomes essential. 

A note of caution, though: checklists don’t work for everything. When you need substantive product documentation that describes how to implement or use an entire system, a checklist may not be enough. As this article from the Nielsen Norman Group points out, some companies make the mistake of substituting feature checklists for substantive information on how to use or understand the product or service. For more guidance on using checklists well, see this article.

Still, used properly, checklists and other documentation can reduce risk and increase efficiency. That’s what we help you do!

Plain Language and COVID-19

It’s always important to use plain language in communicating with your intended audience. But it’s even more critical when emotions are running high. That’s certainly the case during this COVID-19 crisis. So what can you do to ensure that you communicate in plain language during a time of trouble?

General guidance

Here are the basic rules to follow to ensure that you’re ready to apply plain language principles during a crisis:

Be prepared 

Be Prepared.png

Scar was right. (More about how this image relates to plain language later.)

You need to be properly trained to communicate via plain language before a crisis hits. It’s hard to learn any new skillset on the fly (though we can make it easier). 

 

Take advantage of customized training

Since extended in-person trainings are out of the question during a time when any moderately-sized gatherings are taboo, consider web-based trainings as an alternative. Even for groups that are swamped, it’s often possible to insert a lunch and learn training, or something similar. Be careful, though – not all in-person training translates well to webinars. You need to make sure the trainer is skilled in the online medium. And you should make sure the training relates specifically to the plain language issues you’re currently facing.

 

Review materials to ensure they comply

To stay sharp, you need to review your materials regularly to make sure overly complicated or unclear writing isn’t creeping in. In a crisis, you may not be able to review all your content, so make sure you’ve identified the most commonly used materials ahead of time.

 

Bring in some help

Okay, so maybe you can’t bring anyone in physically. But it’s important to have qualified plain language communicators on call when you do need some added plain language firepower.

 

Applying the principles

Now let’s look at how plain language principles apply during this crisis:

 

Write for your audience

This is really the core of all communication, right? But it’s even more critical right now. You may be creating content for a different audience now than you normally would. Even the regular users of your content may be in a more tense state than usual. That’s going to affect the information you present.

 

Organize the information

Do you understand the tasks that people who access your content are trying to complete? What questions might they have about COVID-19? Make sure you answer those questions specifically, up front.

 

Choose your words carefully

And images. For example, how many people recognize the image of Scar above, and the reference to the Lion King Disney movie? Probably most of you. But if you’re communicating information that will impact the health and safety of thousands or millions, you can’t afford to lose even 20% of your audience with an unclear cultural reference (I intentionally included the image above to illustrate this point).

 

Be concise

Users are almost always looking for specific information when they access your content. This is especially true for COVID-19 content. They’re trying to make important health decisions. No extra words, please.

 

Keep it conversational

This is a tricky one. As always, you should avoid writing to “sound smart”. But people aren’t looking for you to communicate about the crisis in wacky ways. Don’t outsmart yourself in how you present content, but it’s especially important to communicate in an orderly, distraction-free way.

 

Design for reading

In other words, convey your content in a way that people can find what they need quickly. Design so that they can find information right away. You can’t afford to focus on yourself.

 

Follow web standards

If your content is on the web, make sure you:

-Lead with the most important content

-Write in chunks

-Cut anything unnecessary

These guidelines are always important – parts are included in the guidelines above. But if you don’t follow these guidelines for crisis-related content, people will drop your site even more quickly than usual – perhaps never to return.

 

Test your assumptions

A wise software engineer once told me “The first version of anything stinks.” Unless you’ve put the information in front of real people who need it, there will be gaps and problems that you will not have anticipated ahead of time. So put your content in front of a small group of representative people whenever possible, before you release it to the general public (let us know if you need help with the logistics of gathering this feedback).

Going forward, make sure you provide a convenient feedback mechanism, so that people see right away how to contact you when something in your content doesn’t make sense to them.

Good luck, and stay safe!

The Value of STC

By Jordyn Sessoms & Daniel Maddux

Intro

This article addresses the the value and benefits of the Society for Technical Communications (STC). Individuals who are interested in accessing the “best-in-class” technical communication education, resources, and services can highly benefit by joining STC. To benefit fully from the employment, educational, and networking opportunities that STC membership provides, students, professionals, and organizations should consider becoming members.

 

Jobs and employees

STC is a great place to form connections, and potentially land a new gig. It’s also a great place to find high-quality employees if you’re hiring.

Daniel: However, in my experience, job-seekers, and employee-seekers, don’t make up the majority of attendees at most STC events. They are just part of a professionally diverse community. Most members simply enjoy learning and networking throughout their time with a particular employer.

 

Education

One of the chief benefits STC provides is the chance to take advantage of educational opportunities. Members can join chapters and Special Interest Groups (SIGs) to build lifelong relationships and access the global community. These groups hold regular meetings, which are usually open to the public, at which you can stay up to date on the newest trends and tools. Members can join by either geographical location or by area of interest. You can also access live webinars, online certification courses, and publications such as the Intercom and Technical Communication.

 

Certification

The STC offers numerous online certification courses. The STC currently provides six continuing education units. The length of the courses can vary and take up to several weeks to complete. The idea with certification is that you can show your dedication and legitimacy to employers, and thereby differentiate yourself when seeking a job. These offerings can also be useful as a means of keeping one’s skills sharp.

 

Support

One of the often unacknowledged benefits of participation in STC is the camaraderie and support found in STC communities. It’s surprising how tech writers across industries and organizational levels struggle with the same problems: lack of access to SMEs, having writing projects thrown over the wall, being the first people jettisoned in a downturn, etc. STC members know how to help you overcome these struggles.

 

Broad focus

STC is the only organization of its kind for general technical writing (though there’s AMWA for medical writers, APMP for proposal writers, the IEEE professional writing component, and the ATTW for tech comm teachers, among other groups. STC’s broad focus makes it an excellent source of best practices and learning across industries.

 

Conclusion

The STC provides access to optimal career development, professional networking, and professional and educational materials as it advances of theory and practice of technical communication. As a result, the society’s members spread throughout the field, benefitting various countries and industries. STC is a great candidate for individuals who are looking to join an organization that will provide them with excellent training and networking that they can put to use immediately in their jobs.

 

Zombies Are Not a Knowledge Capture Strategy

The situation

The manager of finance department at a major energy company had a big problem. John, the most senior accountant, was preparing to retire.

John knew everything that went on in the department. The trouble was, there were parts of the job that only John knew about. There was a big concern that once John left, there would be gaping holes in the daily and monthly processes.

What can you do in that situation? Well, normally you might ask John to just tell his co-workers what he does. He might write up a series of documents detailing his normal processes. He would then sit down and explain the documents to the people who would be taking over the different parts of his process when he left.

The trouble was, John had trouble communicating what he did to others. First of all, he was too busy to spend much time writing. And when he did finally sit down to write, he would put together big, confusing documents. The documents would ramble here and there and everywhere, while leaving out massive amounts of necessary information. John was a true expert, and so he assumed those he was writing for would know what he knew.

So what can you do? How can you extract the information in John’s head, and provide it to the people who need it? Will you just have to wait for the zombie apocalypse?

How bad it can get

Pick up any trade magazine, for any industry, and you’ll probably see an article on this problem. Baby Boomers are retiring, and newer, younger employees are not staying in one position very long. This leads to a massive brain drain at many companies.  This trend is especially troublesome in the energy industry, but it is impacting all other industries, as well.

When you hire a new employee, it is more important than ever to be able to get them up to speed quickly. Otherwise, knowledge from the previous generation of workers will be lost, and the new generation will have to relearn the same information and lessons over and over again.

It’s a real challenge to prevent that from happening. I spoke recently with a VP at a major energy company. She told me that some of the knowledge capture strategies she had tried had been partially successful. But there was no set standard that companies were using across industries to make sure that they were keeping critical knowledge within their business.

But you aren’t helpless.

Let’s reexamine the situation that John’s manager found himself in. Who was John trying to help with his writing? Who would be using John’s documentation, actually? Probably not an expert at the level of John himself. Most likely, it would be a newer employee, perhaps a younger employee.

What to do about it

Follow these steps to make sure that you capture needed information from employees before they leave:

  1. Think ahead.Before you get down to actually writing the information up, you need to do some prep work. This will ensure that you get the maximum benefit out of the effort you’ll be undertaking. Be sure to cover the following:
  • Recognize that information is a critical business asset. The information that your employees possess is what makes your business run. If that information gets up and walks away, you’re sunk.
  • Prioritize the most critical information. When any of your employees leave, it can be a blow to the business. But you and I both know that some information is more important than other information. Think about the critical processes in your business, and who makes them go. If Jack retires (or gets sick for a while), does anyone else know how to make sure the invoices are handled properly? If Maria, who is the only person who knows how to make sure the XYZ balancing process is done correctly, is suddenly out of the picture, what kind of damage would that do?
  • Communicate the need to employees. You need to emphasize how important it is to capture how your employees do their work. Make sure they know that you’re not trying to replace them, or play big brother. Actually, you think they’re so important that youhave to write down what they know. That way, you’ll have an insurance policy of sorts if they ever do check out.
  • Prepare to allocate resources. The people who know your business or department the best are the ones that will need to devote time to the documentation effort. Make sure they know that they will be expected to contribute. At the same time, recognize that they may need to push one or more of their current duties to the back burner for a bit to make time to work on documentation.
  1. Prepare your employees. Every once in a while, I run into an employee who doesn’t want me to help document their critical tasks and knowledge. They are afraid that if I do so, their employer will just lay them off and replace them with someone younger and cheaper.
    Perhaps that does happen in a few cases. But it’s never happened on any of the projects that I’ve worked on. Smart organizations document their employees’ key tasks and knowledge because they want to have something to fall back on if that employee is suddenly gone from the company. The company would rather keep the person, in nearly every case. But the documentation serves as a kind of insurance policy.
    You only take out insurance policies on things that are precious to you. Make sure your employees know that the documentation effort is an expression of how much you value them.
  2. Get organized.Once you’ve gotten your vision straight in your head, it’s time to plan the execution. Use the following guidelines in deciding how you want to document what your employees know:
  • Decide whether you will complete the writing in house, or if it’s a better idea to get outside help. Whichever option you choose, make sure your writer is an expert at communicating financial information. They should also be skilled at writing in plain English.
  • Think beyond just creating or revamping a few documents. You will get the most value if you set up reviews, deadlines, and future revamps in an efficient way. Merely creating documents per se isn’t enough. You need to think about how the documents will be put together step by step, and how they will be distributed. Someone who is trained to communicate technical information can help with this.
  • Involve writing resources early. Whether you use an inside writer or outside help, make sure they’re involved as close to the start of the planning process as possible. If you’ve already set up the project goals and organization, and you’re just now telling the writer you want their help, it’s too late. You won’t get as much value as you should.
  1. Get it done and follow through.I’m not going to lecture you on the principles of project management. If you’ve completed steps 1 and 2, step 3 should be simple. As always, be quick to communicate, and hold people to doing what they say they will do. Then make sure to follow up with any periodic updates or reviews that you schedule.

By following these 4 steps, you can capture the critical content that exists in the brains of your employees. This will help you minimize your losses when an employee leaves, and get the remaining, or new, employees up to speed quickly.

No zombies needed.

Use Writing to Bridge Generational Gaps

 

The situation

The finance department at a major energy company had a big problem. John, the most senior accountant, was preparing to retire.

John knew everything that went on in the department. The trouble was, there were parts of the job that only John knew about. There was a big concern that once John left, there would be gaping holes in the daily and monthly processes.

What can you do in that situation? Well, normally you might ask John to just tell his co-workers what he does. He might write up a series of documents detailing his normal processes. He would then sit down and explain the documents to the people who would be taking over the different parts of his process when he left.

The trouble was, John had trouble communicating what he did to others. First of all, he was too busy to spend much time writing. And when he did finally sit down to write, he would put together big, confusing documents. The documents would ramble here and there and everywhere, while leaving out massive amounts of necessary information. John was a true expert, and so he assumed those he was writing for would know what he knew.

 

How bad it can get

But who would be using John’s documentation, actually? Probably not an expert at the level of John himself. Most likely, it would be a newer employee, perhaps a younger employee.

It’s always tough when an experienced employee leaves the company. But it’s especially difficult when dealing with the new generation of employees. Younger accountants and CPAs, along with their peers in other industries, have different priorities than previous generations. They are not as likely to stay with one company for many years. They come in and learn and leave. So the brain drain is even more extreme than it has been in the past.

So when you hire a new employee, it is more important than ever to be able to get them up to speed quickly. Otherwise, knowledge from the previous generation of CPAs will be lost, and the new generation will have to relearn the same information and lessons over again.

 

What to do about it

Follow these steps to make sure that you capture needed information from employees before they leave:

  1. Think ahead. Before you get down to actually writing the information up, you need to do some prep work. This will ensure that you get the maximum benefit out of the effort you’ll be undertaking. Be sure to cover the following:
  • Recognize that information is a critical business asset. The information that your employees possess is what makes your business run. If that information gets up and walks away, you’re sunk.
  • Prioritize the most critical information. When any of your employees leave, it can be a blow to the business. But you and I both know that some information is more important than other information. Think about the critical processes in your business, and who makes them go. If Jack retires (or gets sick for a while), does anyone else know how to make sure the invoices are handled properly? If Maria, who is the only person who knows how to make sure the XYZ balancing process is done correctly, is suddenly out of the picture, what kind of damage would that do?
  • Communicate the need to employees. You need to emphasize how important it is to capture how your employees do their work. Make sure they know that you’re not trying to replace them, or play big brother. Actually, you think they’re so important that you have to write down what they know. That way, you’ll have an insurance policy of sorts if they ever do check out.
  • Prepare to allocate resources. The people who know your business or department the best are the ones that will need to devote time to the documentation effort. Make sure they know that they will be expected to contribute. At the same time, recognize that they may need to push one or more of their current duties to the back burner for a bit to make time to work on documentation.
  1. Get organized. Once you’ve gotten your vision straight in your head, it’s time to plan the execution. Use the following guidelines in deciding how you want to document what your employees know:
  • Decide whether you will complete the writing in house, or if it’s a better idea to get outside help. Whichever option you choose, make sure your writer is an expert at communicating financial information. They should also be skilled at writing in plain English.
  • Think beyond just creating or revamping a few documents. You will get the most value if you set up reviews, deadlines, and future revamps in an efficient way. Merely creating documents per se isn’t enough. You need to think about how the documents will be put together step by step, and how they will be distributed. Someone who is trained to communicate technical information can help with this.
  • Involve writing resources early. Whether you use an inside writer or outside help, make sure they’re involved as close to the start of the planning process as possible. If you’ve already set up the project goals and organization, and you’re just now telling the writer you want their help, it’s too late. You won’t get as much value as you should.
  1. Get it done and follow through. I’m not going to lecture you on the principles of project management. If you’ve completed steps 1 and 2, step 3 should be simple. As always, be quick to communicate, and hold people to doing what they say they will do. Then make sure to follow up with any periodic updates or reviews that you schedule.

 

By following these 3 steps, you can capture the critical content that exists in the brains of your employees. This will help you minimize your losses when an employee leaves, and get the remaining, or new, employees up to speed quickly.

 

 

 

The Overthrow of King Content

Intro

I recently presented this content at a meeting of the Greater Houston Chapter of APMP.

To see my presentation, you can review the SlideShare here.

We all know that, when it comes to a technical documentation, content is king. If we don’t have good, accurate, complete content, our documentation will fail. We can nail the grade level of the writing, and have excellent organization. However, without excellent content, those things are meaningless. Content is the King.

But at the same time, we can have great content that fails. In those cases, King Content is deposed, overthrown by issues that should never come up in the first place.

So what are the problems that ruin good content? Who are the plotters that overthrow King Content, and put the focus of our writing exactly where it should not be?

1. Overly complicated writing

A quote from Warren Buffet’s preface to the SEC Plain English handbook:

“Perhaps the most common problem, however, is that a well-intentioned and informed writer simply fails to get the message across to an intelligent, interested reader. In that case, stilted jargon and complex constructions are usually the villains.”

We must always ask ourselves a question when we read any technical document. That question is: “Did I understand this the first time I read it?” If a user will not understand the sentence, paragraph, or document the first time they read it, then you’ll probably lose them.

Now, it’s one thing to read something that someone else wrote, and identify some issues. But what if you wrote it yourself? Just about anything you write will make sense to you, since you’re the one who wrote it. And putting a document away for a couple of days isn’t a luxury we always have.

So what do you do? Use metrics. If you’re using Microsoft Word, then this is easy. Just enable the readability statistics add-on for the spell checker. Then you can review anything from a single sentence to an entire document, to see if it contains an appropriate level of complexity.

For the steps involved in enabling readability statistics, see Microsoft’s article on the subject.

2. Vendor-focused writing

“One the biggest problems with the text in proposals? Talking about your own company WAY TOO MUCH! The focus should be on the client. I try to use the rule of using your clients’ name three times more than your own.”

Krissy Chaney

Proposal Writer at RTL Networks, Inc

It’s easy to slip into the habit of focusing on our own company, or our own technology. For documents that are aimed at a particular client, we may wind up talking about our company and its solutions much more than we discuss the client and their needs. Oil and gas companies may focus on their equipment or services, and forget that the client doesn’t care about those things (they only care about their needs). Software companies may produce documentation that delves deep into the inner workings of their product, but that doesn’t address how the features actually meet the customer’s needs.

What do we do to resolve this problem? First, count.

How many times in the document did you mention the client and their needs, versus your versus your own stuff? If the ratio isn’t at least 2-1 or 3-1, you may have a problem.

We can skip a lot of the problems associated with vendor-focused writing if we’ll take the time to plan the focus of the documentation up front. If we’ve decided as a team not to focus on ourselves, we’ll be more likely to wind up with the right result in the end.

But what if you have already received a document that is obviously written in a vendor-focused way?

You’ll need to perform triage. You need to know which sections are most important in the document. Is the most important section the executive summary? Is it the introductory content? Is it a key procedure midway through the document? Identify the key sections, and make sure they’re as client-focused as possible.

3. Glaring text errors

“Do not tolerate any mistakes.”

Elite Documentation Employee Standards

This one is pretty simple. You can handle it by reading over the document, and asking “Does any of this make us look dumb?” And “Which typos might make us look the most dumb?” Again, prioritize, and focus on sections and types of errors that could do the most damage to your company’s professional credibility.

Using a different set of eyes really helps for this one. I’ve become a very good writer, but I’m not God. My writing is almost never completely free from errors. No one’s writing is divine.

4. Schizophrenic writing

“Different authors may yield different styles or voice. These differences may also manifest themselves with the facts … Somebody has to do a “horizontal alignment” check.”

Al Pena

Principal at A&M CoOp

If you start encountering a lot of different voices in your technical documents, you should ask yourself, “Do we have a pre-existing standard?” When deadlines are looming, it’s not the right time to come up with standards. The right time to come up with writing standards is before the project even kicks off.

I remember working on a $1.5 billion proposal a few years back. I fielded question after question about what the “right way” to format something was. I helped the team come to consensus, but I couldn’t help wondering to myself, “Why are we just asking these questions now?” Companies need to have a style guide before writers even start working. Otherwise, decisions become very haphazard.

It also helps to have a rational workflow. To explain what a rational workflow might be for your company, let me explain the different kinds of editing that your documents need. (Keep in mind, I’ve written some of the following information from a proposal writing perspective. The workflow you use in your company might be much different. The important thing is that your workflow makes sense, and produces good results.)

Once you’ve gathered your content, it’s time to do a substantive edit. The substantive edit is different from the proofread in that a substantive edit asks the question, “Does this really make sense? If not, how can I rewrite this sentence or section or table header to make sure it does make sense?” Of course, depending on the volume of work that you have, you might not be able to do a substantive edit on all of your content. You need to prioritize which sections have to make sense. Then focus on making sure the writing in those sections is crisp and clean.

After the substantive edit, it’s time to proofread and copy edit. This will be relatively quick easy if you have a good set of standards. If you don’t, people will continuously make adjustments based on their own preferences. That will reinforce the schizophrenic voices that you are trying to silence.

5. Embarrassing boilerplate

“Nothing says “I don’t give a fig” like calling the customer Acme Manufacturing when their name is Amalgamated International.”

Peter Baron

Head of Bid Management at Bull Information Systems

If your documentation projects tend to be similar, but not exactly the same, for each customer, then you may have seen some embarrassing boilerplate. (Boilerplate is text that is reused over time for multiple clients or projects.)

If you use boilerplate, you must ask yourself, “Which parts of this document will I need to customize for this customer?”

You need to have a list of the places in each document where you need to customize the information. You don’t want to get in a crunch, and then have to search frantically for each instance of text that refers to a different customer. You won’t find everything, most likely.

For this effort to make sense, you also must have a good style guide, with standard terms your employees should use. This will help you with global searching and replacing, especially in Microsoft Word.  If you refer to a customer as ACME, ACME Inc., ACME Amalgamated Inc., and ACME incorporated, you will have a much harder time getting everything updated.

Boilerplate tends to hurt the quality of many kinds of documents. But in the software industry, and in certain industry niches, boilerplate is critical.

May this this article help your content grow stronger. Long live King Content!

How Writers Can Work Efficiently with SMEs

 

Introduction

One of a writer’s main responsibilities (especially if the writer is communicating technical content) is drawing information from subject matter experts (SMEs). Here are the main four principles a technical communicator should follow when working with SMEs.

1. Organize the work properly up front

Without this step, you may be doomed. Whether you’re kicking off a new project, or working to continuously update technical documents, make sure you:

  • Know who exactly you’re writing for
  • Have a feel for how and when the technical information will be used
  • Know your complete scope of work
  • Know exactly when everything will be due
  • Understand the priority of the work

Many managers and clients will gloss over this critical analysis. Don’t let them. Your relationships with SMEs will get really sticky very quickly, otherwise

2. Be persistent

Once you’ve started gathering the content for your manual, help system, or other document, you’ll get some push-back. Most people are busy, as a rule. Don’t take it personally if someone puts you off.

At the same time, if you let that go too far, deadlines will be missed. And you will be blamed, at least in part, even if you don’t think it’s your fault. To avoid that, you need to use several basic techniques to overcome SME roadblocks:

  • Light: Try to develop your relationship with the SME.
    Smile at them. Leave them a thank-you note when they give you what you need. Always be on time. Be very good at your job. Be available to help, quickly. Explain any changes you think should be made.
  • Medium: Communicate regularly with the SME’s superior.
    You don’t have the authority to set priorities for the SME. Their manager does.
  • Heavy: Sit down with the SME and their manager to go over the problem, and your proposed solution.
    Don’t be afraid to do this. Your company/client may thank you later.

3. Don’t make mistakes

There are a few cardinal sins that can ruin a technical communicator’s relationship with a SME. Your relationship can recover after making one of these mistakes, but it will be difficult:

  • Waste the SME’s time.
    You can’t arrive late to meetings. And you can’t ask for a meeting that you don’t really need. More than anything, you can’t waste work the SMEs have already done for you. If you make a habit of misplacing document markups, you will soon find yourself out of a job.
  • Fail to understand concepts.
    A new tech writer had an hour-long meeting with a SME (an engineer). The SME spent the better part of the meeting trying to explain an engineering concept to the writer. She just couldn’t understand what he was talking about.
    Then the writer and engineer went to lunch with a group of co-workers. At the restaurant, the writer laughed at the restaurant for the glaring typo she found in their menu. The engineer was disgusted.
    You don’t have to be an engineer in order to communicate technical content that relates to engineering. But if you can’t understand basic concepts quickly, you’re in the wrong field. No one will care how good of a proofreader you are.
  • Fail to prove your own skillset.
    You’re supposed to be a great writer. You’re supposed to know how to analyze and organize content better than other people. That’s why you have a job.
    So if you write emails with typos in them, or turn in documents with grammatical errors, you look like a fraud. We can’t do that to ourselves. If that means you have to stop emailing from your phone, because you misspell too many words that way, so be it.
  • Be a dork.
    Most writers already have a tough enough time earning credibility, and proving they’re not just a hack, a frivolous cost center. You must look nice. You must talk nice (up to a point). Sounds soft, but basic social grace goes a long way towards making things work out.

4. Learn new techniques

There are a myriad of ways to get the information you need to put together a good manual, or process document, or proposal, or whatever. Don’t get stuck on one.

If you get into a new position or a new project, and the way you’re working with the SMEs isn’t working for more than a couple of weeks, don’t sit around and wait for things to get better. They usually get worse.

Examples of how you might change tactics:

1. You are working with a senior-level accountant who is responsible for some key financial reports at an energy company. You need to document how they put together those reports. The accountant is supposed to write up a rough draft of the procedure and related information, and send it to you to clean up.

But they just can’t seem to find the time to get it done. What do you do?

First, ask for a brain dump. “Don’t worry about making sure everything is in there, or that you’ve covered every single step or possibility.” Have them send you a mess of information, then organize it and review it with them. You must be able to deal with dense, jumbled clumps of technical content.

If that doesn’t work, ask to sit with the SME the next time they complete the procedures. You may be able to capture the content you need by doing a couple of runs that way. And you can avoid slowing the SME down too much.

2. You are working with 5 engineers to document how one of their drilling systems work. You are able to schedule meetings with 4 of the SMEs, but the fifth won’t return any emails or phone calls, or make eye contact with you in the hall. What do you do?

Of course, you should try all of the tips above. But sometimes even the best techniques don’t prove to be effective every time. Look for something new.

Remember that incentives can also be helpful. Ask the SME’s manager if they can offer a carrot (or a stick) to their employee if they do/don’t get the work done on time.

Now, for a contractor or a technical communication firm like EDI, offering incentives directly isn’t legal. But there are some creative ways to help SMEs feel like they’re moving towards a great end point.

EDI is working on some innovative solutions in that regard. When we have them ready to go, we would be happy to share our method with you.

Critiquing an Engineering Technical Writer Want Ad

Introduction

For a while now, I’ve been running across want ads for technical writers in the oil and gas industry. I have noticed some huge problems with how many of the broken want ads are written. I’ve also come across a few gems. I’m going to share one of each type here.

While these problems are present in ads for tech writers across industries, they are most evident in the oil and gas industry.

The bad one

Here are some excerpts from an example of a bad tech writer want ad (email us for the full version):

“… We are currently recruiting for a Technical Writer with an extensive background in oil and gas and/or petrochemical industry. This is for a long term contract opportunity with a fantastic company in Houston. This position is at 4 to 6 months, poss. longer”

We’ll ignore the minor grammar faux pas (I’ve written elsewhere about how technical communicators shouldn’t be too hard on others’ writing mistakes, but should seek to eliminate all of their own. The biggest problems are the focus and the scope of the qualifications here.

What exactly does an “extensive background in oil and gas and/or petrochemical industry” mean? If I have worked on newsletters for 20 years for an upstream oil company, does that mean I’m qualified to write safety manuals for a midstream gas company? When you move from niche to niche in oil and gas, most of the processes and terminology change drastically. There’s really no such thing as a “background in oil and gas,” when you get right down to it. The fields of oil and gas are too broad for that.

“The Technical Writer (Engineering) will write, format, edit, and validate technical documents to generate operation and maintenance manuals according to client and product requirements. 
Under close direction, compile data from various sources to be included in project manuals.
Keep supervisor updated on all current issues pertaining to engineering standards manuals.
Excellent written and verbal communication skills.
Thorough knowledge of products/services.
Advanced PC Skills.”

Wait a second. Is what’s most important that the writer knows about some area of the oil and gas industry, or is it that they can organize technical content, and write well? Is writing just an afterthought? Which products/services should they know about? And what are “Advanced PC Skills,” and which ones should the writer have?

Really, what many oil and gas companies want more than anything when they say they want a writer with an extensive background in oil and gas is someone who is willing to write, who knows a particular subset of terminology. They want a terminologist more than a real technical communicator. Is that wise?

Look at this simple graphic:

Overlap between terminology and writing ability

The red is all the people who know a lot of terminology in a particular area. The blue is the people who know how to write and organize technical content, generally. The purple is the people who know a lot of the terminology in that area, and have the ability to write and organize technical content, too.

Narrowing the candidates down to only those who know a particular set of terminology makes the graphic look more like this:

Most terminologists cannot organize content

So what happens? There is almost no chance that the company will hire someone who will do a good job of writing and organizing the content. So the company comes to believe that there’s not much to be said for technical communication. They might as well just hire someone who will write, and make sure they know the terminology. And so the cycle continues.

How do you break that cycle? Check out the following ad.

The good one

Here are excerpts from a far superior ad, from a company that works with oil and gas companies. (Email us for the full version.)

“Technical writing company seeks energetic, enthusiastic, flexible
employees for immediate employment. 

Must have a great attitude and good command of the English language (to
do editing and/or writing of technical documents).”

So I know something about the company culture, and I know what my key role will be.

“Sr. Writer revises or originates technical content according to client
requirements using resources provided by the client. The writer may work
on the client site or in our office. Skills used regularly are 1) target
audience assessment 2) content assessment 3) consulting with client on
document design 4) content organization 5) document formatting 6)
document editing.”

Aha. So it’s saying that my key ability on the job will be to be able to take the right technical content and make it work for the right people. This isn’t talking about a hack who knows some terms. This is an expert in their field.
“Must be an advanced user of MS Word and skilled in the application of
templates and styles. Must be proficient with Adobe Acrobat
Professional. Advanced proficiency preferred with PowerPoint, Excel, and
Visio. “

Again, this is specific. I know exactly which software packages I need to be familiar with before I apply here.

“Requirements:
– 4 – 6 years’ technical writing experience with an emphasis on
procedural writing
– Bachelor’s degree or equivalent experience
– Oil and gas experience is a plus
– Supervisory experience is also a plus”

Again, very specific. And “oil and gas experience” is a valid qualification, even if it shouldn’t be the primary concern. Why? Not because it actually helps you much when it comes to writing and organizing the content. But because prestige is very important throughout the oil industry and the gas industry. And being able to say “I have oil and gas experience” can help get your foot in the door at many companies, even if won’t make you more competent.

And I do have oil and gas experience.

Top 10 Ways to Increase Your Value as a Technical Communicator

Here are the top 10 ways a technical communicator can establish his/her value:

10.  Embrace your personality. If you’re an introvert, be thankful. It takes solitude and lots of thinking to produce really good documentation. At the same time, if you’re one of the rare extroverts in this field, you have a leg up in getting people to value your work.

9.    Get them to bring you in early. Whether you work for a company or are an independent, research shows that the earlier in the process you get onto the project, the more successful you (and the project) will be.

8.    Recognize that your career is a marketing project. Everyone we know, from business contacts to friends to churchmembers to our old, kooky Uncle Murphy should know what we do, and how that benefits our companies.

7.    Set some goals. How are you going to get to the point whereat those you work with will treat you and your work with real respect? What would have to happen for that to occur? What certifications or degrees would help you establish your credibility more?

6.    Market yourself through your writing. You’re a writer, after all. About the best way you can show others your value is through your writing. Whether it be with notes of appreciate, emails that never have typos, or a friendly reminder telling your supervisor what all you’ve been doing to save the company money, do put yourself out there.

5.    Not everyone has to like you. The important thing is that we’re professionally appealing to a few important people. Don’t go into work saying “I hope I don’t get in trouble for anything today.” Go in saying “I’m going to create real value through my work today, and I hope I don’t have to kick anyone’s behind to make that happen.” That’s hard to do for most tech writers, but it can be the difference between success and failure.

4.    Take on real responsibility. Maybe marketers and other communicators recognize this need more than technical writers do, and that’s how we end up with VPs of Marketing, but no VPs of Technical Communication, except at specialized companies. This includes taking responsibility for your own continuing education.

3.    Refuse to be blown off. Who hasn’t been shrugged off by multiple SMEs who either tell us they’re “just too busy,” or simply ignore us? You have to be willing to, first, develop a real relationship with the SME. Then, you must have the guts to march into that SME’s office and confront him or her if s/he is keeping you from getting to where you need to be.

2.    Don’t be too thankful for your job (or clients). By that I mean don’t adopt a dependent attitude towards any one client. As a business owner, about the only thing worse than hearing an unemployed technical communicator say “I’m not sure if I really want to be working in this field or not” is hearing “Oh, would you give me a job?” Your job isn’t a gift. You earned it by virtue of your abilities.

1.    Eventually, at some point, the technical communication industry has to move away from hourly billing. Hourly billing has no relation to the actual value we provide to businesses. As a result, our earning power has been vastly reduced, and companies tend to get rid of us as soon as possible. When our industry finally gets a handle on the impact that good technical communication has on companies’ bottom lines, we’ll all be sitting pretty.

 

How to Use Writers Effectively

Purpose

The purpose of this document is to help you find writers who can do what you need them to do, and to help you use them well once you find them.

Test them up front

Maybe you’ve had a bad experience with a tech writer in the past. Or maybe you’re not sure if the person or company that wants to write your manual or other document can do the job. That’s a reasonable concern. So what do you do?

Linscomb & Williams, a top-25 money management company in Houston, was faced with that situation a few years ago. They wanted to rewrite some of their client documentation in Plain English. But they needed someone who could do that while keeping the information technically correct.

In that case, EDI got the project. But what if EDI’s tone or method of laying out information didn’t match what Linscomb & Williams were aiming for? Then they would have had the opportunity to select another vendor that fit their culture better. Taking the time to test out potential vendors up front helped Linscomb & Williams make a good decision.

Get them involved up front

A December 2006 Aberdeen Group report states that project documentation meets expectations 92% of the time, when writers are involved up front. When the writers are involved later, the success rate for the documentation falls off precipitously.

You want to involve the writers early and often in the project discussions. This will help them to gain a clear understanding of where we’re trying to head with the project, and therefore, with the documentation. It will also give them a chance to guide decisions that will impact documentation, so that the end result is high-quality, usable writing.

And maybe you’ve struggled with a writer who is so introverted that all they want to do is sit in the dark and write. This is a way to help them be a connected part of the team.

Don’t try to make the writer a subject matter expert

I run into businesspeople all the time who are looking for a writer who is well-versed in the lingo that they use in their business. I’ll admit, for the sake of prestige a writer may need to know some terminology in order to get their foot in the door.

But you probably know way more about your business, your clients, and your terminology, than any writer ever will. A good technical communicator knows more about planning documentation, structuring documents, and producing clear writing than you do (assuming that’s not your profession).

So let them do their thing. The best documentation usually comes from a pairing of motivated subject matter experts and technical communicators who are very good at drawing out the correct information, and expressing it clearly in writing.

Focus on the value of the writing, not the hourly rate

If you’re just looking at your writer as someone who produces content as a commodity, then you probably won’t get much bang for your buck. You’ll likely wind up wondering if it makes sense to pay a writer to produce content.

There are several reasons why people have this attitude issue.

One is that writers are often tasked with documenting features, not benefits. So your customers wind up seeing lots of information about your equipment. But they don’t have much insight into how your products or services can help them, uniquely. That kind of writing doesn’t produce the results you’re looking for.

Another is that people are used to asking writers to carry out solutions, rather than asking them to solve problems. As with everyone who works for you, if you can get them focused on solving problems themselves, rather than just carrying out your detailed game plan, you will get more bang for your buck.

Also, if you don’t determine what the value of the work is supposed to be ahead of time, you may not see much value in the work at the end of the project. Be sure to carefully define what it means for the documentation for the project to be “successful”.

If you’re still not sure if your writers are producing what they need to, look into using metrics to compare one writer’s work with another’s. Just keep in mind, no metric is foolproof. You need to include both quality and speed, as well as other factors that are applicable to your business (see this article from idratherbewriting for more information).

Finally, show your writer(s) that you value their work. If you are focused on seeing value in their work, they will be more inclined to do so, also.

Tell them when it’s due when you ask for their help

This is an obvious one. But we miss it all the time, don’t we? If your writer doesn’t ask when something is due when you ask for their help with it, then tell them. All kinds of chaos ensue when writers don’t know what their deadlines are.

Learn to use scribes

Were you not expecting this one? If you’re going to use writers effectively, you need to learn to use them in new ways.

A scribe, also known as a technographer or a chart writer, can make you look like a genius in meetings that you lead.

A scribe’s task is to take things off of your plate during a meeting, so that you can focus your efforts on driving the discussion. These tasks may include:

  • Recording action items and key decisions
  • Taking minutes
  • Running the computer/projector
  • Manipulating documents during the meeting

A scribe can be your right hand man or woman in a meeting. They are an almost invisible, valuable aid. Use one.