Technical writing

Tip #11–Use plain language when conveying technical information

Posted on August 17, 2007. Filed under: Blog--All categories, Management development, Technical writing |

Gobbledygook, jargon, geek-speak. Whatever you want to call it, it’s not language the everyday reader understands. Maybe the author’s intent is to try to impress the reader; perhaps the technical language is deemed necessary to convey the message; or maybe the writer just doesn’t understand that not everyone of us reads and speaks the same language. Whatever the reason, the point is this: language must be plain and unambiguous if it is to be understood by the common reader.

Tip #11 states:

Consider using stories or analogies to convey difficult technical information. This helps the receiver of the message maintain a sense of confidence and understanding, whereas that same person may feel insecure or defensive when hearing unfamiliar technical language.

What is the purpose of putting something in writing anyway?

For most authors–whether you are the author of a technical document, a set of instructions, or a simple business letter–the reason for writing is to convey some information to the reader so the reader can take the appropriate action. The problem we encounter when writing in technical language is that our readers often don’t have the same level of expertise that we do; so when they read our document, they are left with uncertainty about what we want them to do and how we want them to do it. We’re much better off writing at the simplest level possible to ensure the greatest possibility of understanding.

Wait a minute! Isn’t that insulting to our readers? In a word: No. Rather than be insulted by documents that are easy to read, easy to understand, and easy to act upon, our readers are going to send up silent praises! They are going to see the stark contrast between the usual convoluted messages they get and our clear, concise messages. They are going to begin looking forward to hearing from us while dreading the prose of others. And when it comes down to who gets the response quicker: that will be us!

What about stories and analogies–do they really have a place in technical writing?

Yes. When readers are faced with unfamiliar information and concepts, they benefit from having them associated with something they easily understand. The more clearly you can connect technical concepts to everyday experiences, the more easily your non-technical reader (or at least the reader who isn’t an expert in your subject) will grasp your message.

When trying to find everyday experiences to explain your topic, think of what we do each day. For example:

  • brush our teeth
  • drive our cars
  • shop for groceries
  • work with our children
  • exercise
  • learn from and teach our pets

I often tell my management clients that working with staff is somewhat like raising children and pets. Children–and pets–respond to praise. So does staff. Children and pets benefit from clear guidelines about behavior and having those guidelines consistently enforced; so does staff. While these are not heavily technical concepts, the message comes through more clearly and easily when it’s associated with a common experience.

When writing, consider your readers’ level of experience with your topic. The more simply you can express your message, the more analogies you can draw, and the more stories you can tell to demonstrate your point, the more easily your readers will grasp your message.

Want some help making sure your messages come through loud and clear? Check out my Document Review Services brochure

Read Full Post | Make a Comment ( None so far )

They just don’t get it

Posted on February 11, 2007. Filed under: Blog--All categories, Management development, Technical writing |

Good writers, you know what I’m talking about. The people who write the worst are the ones who don’t realize just how bad their writing is! We try to show them how to improve their writing, but they just don’t get it. They don’t see the value of paying attention to the details or trying to say things in a different way–a way that takes the reader into consideration, a way that draws the reader into the document and persuades.

At the start of my writing programs, I see two kinds of faces in the room: the faces of those who are thrilled to be spending a day talking about writing and learning ways to improve their craft; contrast those with the faces of those who are there because “my boss signed me up for this course.” This second group is the one who stand to gain the most from my program. That group has the most potential of making some huge strides toward improving the quality of their work. This group also has the potential for making those same huge strides in the course of their careers–if they just understood the importance of good writing to career progression.

Usually, though, it’s the people who are already competent writers that are the most engaged, the most curious, and the most likely to leave the program armed with an arsenal of strategies to be even better. I love having these people in the course!

The ones who are there because the boss made them come are not hopeless. While at the beginning of the program they may be resentful, within just a few minutes they recognize the point of the program and generally see why they were sent to the program. It’s what they do with what they learn that will make the difference in the long run. After all, no matter what the topic it’s up to us to apply what we’ve learned.

The writers who come into the course with some competency for writing generally apply what they’ve learned faster and more systematically. The ones who need the most help may pick an item or two to work on, but without a commitment to improving the quality of their work those things usually fade away. The good news is, though, that they’ll never completely lose what they learned. It’s in there, and someday they’ll pull the information back out and apply it.

In the mean time, I’ll relish the enthusiasm, energy, and curiosity of the competent writers in my programs. I do believe their enthusiasm is contagious; I’ve seen them “infect” the so-so writers. When that happens, the so-so writers begin to show a little excitement about the potential to improve their work as they see the impact good writing can make in their lives and their careers. Some of the do get it after all.

Read Full Post | Make a Comment ( None so far )

Business Writing at Butte Community Bank

Posted on February 9, 2007. Filed under: Blog--All categories, Management development, Technical writing |

A special Shout Out to Butte Community Bank: thank you for having me back to conduct another “Business Writing” workshop! This repeat workshop is a great opportunity for me to get to know each of you and a great chance for each of you to get personalized feedback on your writing.

I love organizations like Butte Community Bank (BCB): this company values its employees and gives them the training they need to do the very best they can in their work for the company. The staff members I’ve worked with at BCB have all had outstanding positive attitudes and shown a true desire to be the best they can be for the company. That tells me they feel valued at work!

Writing is one of the toughest jobs we have to do in the course of our daily career tasks. For some of us, our customers only know us by our voices on the phone and the emails and letters we send them. For people who work in behind-the-scenes roles, the impressions others form is based solely on the quality of the written and oral communication they receive. Those behind-the-scene workers rarely get a chance to have a face-to-face conversation with a customer, so they have to be especially cognizant of the impression they are delivering on the phone and in writing.

BCB employees understand this and seek out opportunities to improve the quality and effectiveness of their written documents. The writing programs I hold at the bank are energized and exciting. The participants in the program come armed with writing samples and questions. Their goal is to take back with them the tools they need to improve their ability to give excellent customer service. My thanks to each and every BCB member I’ve had the pleasure to work with. You are a great team!

Read Full Post | Make a Comment ( None so far )

Grammar, Punctuation, and Correctness

Posted on January 13, 2007. Filed under: Blog--All categories, Management development, Technical writing |

Ahhh, a day well spent! What’s more fun than spending an entire day focusing on grammar usage, punctuation, and correctness is writing? Spending that day with officers from local law enforcement agencies!

A big shout-out to Beverly Walker of the Regional Public Safety Training Center (RPSTC) for working diligently in 2005 to bring my program, Report Writing Essentials, to the Washoe County Sheriff’s Office and RPSTC. Since the first running of that program, Beverly has been keeping the class full for each session. You go, Bev!

Just last week, our program was filled with officers from Washoe County Sheriff’s Office, Reno Police Department, Sparks Police Department, and Reno-Sparks Indian Colony. Every participant was there for one reason: to improve the reports they write in the course of their jobs.

We focused on the areas that will help them be more successful with their reports: including sufficient detail in the right order with clear, concise, and correct writing so that the people who read the reports will have all the information they need to take appropriate action.

I’m so proud of the officers in each and every one of my courses. They are hard-working, dedicated, professionals with a heart for the work they do and for our community. Thanks so much to each and every one of you for making Washoe County a better place to live!

Read Full Post | Make a Comment ( None so far )

Dangerous Email

Posted on January 7, 2007. Filed under: Blog--All categories, Management development, Technical writing |

I had an experience with email yesterday that reminded me of the dangers of email–especially in a professional setting. The crux of it is that I’d been coordinating an event with several people. The event involved some who were experienced with the requirements of the event and some who were new to the event. To make sure each person was on the same page regarding meeting time, location, transportation, equipment and materials required, etc. I’d sent emails to the group as well as made phone calls to ensure the items were understood and to field any questions the group might have. All was going well.
Then yesterday I received an email from one of the participants, I’ll call her Mary, saying that another of the participants, I’ll call him Jim, had changed his mind about the transportation he was going to use to get from Point A to Point B. No reason was given for the change in plans. As a result of that email, I began to wonder whether this change in plans was indicative of a problem behind the scenes that I wasn’t aware of; if it was to what extent, and did anything need to be done to resolve it.

After pondering an approach for several minutes, an email arrived from Jim. His email explained the situation very differently: the change in transportation plans was not his idea; it was actually a suggestion from one of Mary’s teammates to which Jim agreed.

What’s my point with this story? Is it that I’m a control freak and got twisted because the team didn’t just agree with my plan and move forward? Okay, some people do call me a control freak; but in reality the point is simply this: email does not convey the full story. It is inherently limited in what it can convey because it cannot convey tone of voice; it cannot convey facial expression; it cannot see and respond to the facial expressions of the recipient–facial expressions that might convey a lack of understanding, questioning, disappointment, etc.

While the events related here are rather minor, I saw them as emblematic of how relying on email–something nearly everyone does in today’s communication environment–is not only ill advised, it is a dangerously inadequate tool. Yes, it’s convenient; but sheer convenience doesn’t make things healthy. Consider fast foods and prepackaged meals–a diet based on these has a tendency to lead to unhealthy bodies. And that’s my point with a heavy reliance on email–a communication diet based on email leads to unhealthy relationships because of the potential for miscommunication and the undermining of relationship.

You can still use email to get the job done, but add some face-to-face conversations to the mix. Call people on the phone in addition to emailing them. Reduce the dependence on email and increase the use of other vehicles of communicating. This will help build relationships with the people on your team and give them a sense that you know them as individuals rather than just faceless workers. It’s the relationships we have with others in our personal and work environments that creates our ability to get the job done. Without the relationships, they–and we–are just names in an inbox mixed in with all the other names and junk mail we get.

Read Full Post | Make a Comment ( None so far )

“Dear John” Letters at Work

Posted on January 2, 2007. Filed under: Blog--All categories, Technical writing |

“Is it okay to address an email or letter to ‘Dear John’?” When I heard this question from a client recently, I was flummoxed. Why is this question being asked, I wondered. But then the client explained: “When I have to write to someone named John, I feel weird addressing him as ‘Dear John’ because it’s like writing a break-up letter.” Okay, now I get it!

Yes, it is rather funny to write Dear John when you think about it in terms of a Dear-John letter. Nonetheless, the guy’s name is John; so what can you do? In our informal culture today–and especially in an email–you could always write “Hi John” rather than Dear John. or perhaps just start with “John,” and leave the Dear off. Either way would be appropriate. Another option? Just enjoy the chuckle.

Along the same vein, another client in the same meeting said, “I feel the same way when I have to write to someone named Jean (or Gene). It’s weird writing ‘Hi Jean.'” Okay, this one is MUCH funnier when said out loud. Say “Hi Jean” out loud. What do you hear? Hygiene! Yes, that does sound odd. To solve this you could write “Hello, Jean” or “Dear Jean” and the problem would be solved.

However, it’s always okay just to enjoy a private chuckle and move on rather than try to finagle your way around writing a “Dear John” or a “Hygiene” letter. Besides, we need more humor in the workplace.

Read Full Post | Make a Comment ( None so far )

Liked it here?
Why not try sites on the blogroll...