8 REST API Documentation Tips for Hardware Writers

Technology services based on the representational state transfer (REST) architecture or a RESTful application programming interface (API) are becoming more important for hardware developers and content developers to understand. Wait, what? Why do I have to understand programming stuff? Read more

4 Rules for Business Email – Rule #4

OK. Serious case of writer’s block now for several months – not to mention side work as a contract technical writer.

Soooo, once again, here are my four rules for thoughtful and professional use of business email:

  1. Be Polite
  2. Be Professional
  3. Be Clear
  4. Follow up! (which is an outcome, really, of the first three)

As the rule list suggests, the fourth rule is really a result of conscientious use of the first three rules. Follow-up consists of – Ahem! <embarrassed throat-clearing> – not dropping the ball once it is in flight and also using good networking skills. Both stem from the well-known variation on the golden rule  – you know, the one that says it’s best to try to walk a mile in someone else’s Converse high-tops before you pass judgment.

Converse high top

Dropped-ball avoidance (just developing the sports metaphor here, so please don’t judge!) is a simple guideline to implement. It means that if you started the email string to begin with, you are responsible for closing it out. Typically, you can do that with a summary/next steps email back to all respondents on the string. Summarize the ideas they shared, thank them for sharing, and indicate what you and/or your team will do with those ideas (your next steps).

You can even follow up on the follow-up and go back to the email string after several weeks to inform everyone what steps/ideas you and/or your team have implemented.

You can also take follow-up in a different direction and examine the responses in the email string as jumping-off points for networking opportunities. (And yes, even those of you who are securely employed need to take advantage of networking opportunities.) Was someone included on the email string whom you have never encountered? Was someone on the email string especially critical of your team or their effort? Or did someone on the email string seem to struggle with understanding the topic?

All of these situations represent opportunities for you to reach out informally to the responder and talk – over coffee, over lunch, over Skype, whatever. Get some face time with him/her. Most of the time, you’ll be pleasantly surprised at how much you have in common with that person, and you might even find opportunities in which the two of you can collaborate. In fact, you might just find your next big opportunity professionally through that conversation. Or maybe just your next pick-up ball game. Either way, you’ve pushed beyond the keyboard and made a real connection. Good for you!

For those of you in the U.S., please have a safe and enjoyable Thanksgiving holiday!

4 Rules for Business Email – Rule #3

Is it too late to wish you all a Happy New Year?

OK. It’s been a while. There, I’ve said it. I started another writing gig in late December, and I have been remiss about updating this blog. And I am sorry. On the plus side, I get lots of opportunity these days to put my own words of wisdom into practice. (But, obviously, I am not above punning….)

So – Ahem – to review, here are my four rules for writing professional, business-like emails:

  1. Be Polite
  2. Be Professional
  3. Be Clear
  4. Follow up! (which is an outcome, really, of the first three)

Before the holidays, I got through the first two, so I’ll focus this blog on the third – Be Clear!

Waterford Gifts, Lismore Crystal Bowl 6"

Clarity in emails, like clarity in crystal-ware, is a balance of ingredients. Lead crystal, also known as “flint glass,” is made up of silica and lead; traditionally, in fact, it was 24% lead oxide (which gives flint glass its refractive qualities but is not so good for the human nervous system). Lead crystal is still beautiful to look at. Waterford’s lead crystal chandeliers glitter ever on in Westminster Abby, and Waterford lead-crystal panels comprise the famous New Year’s Eve Ball in Times Square (see how I snuck that in there!). Lead-free crystal is also a balancing act, with various alternative oxides (potassium, zinc or barium) replacing the lead oxide.

Clarity in business emails comes from balancing straightforwardness (for lack of a better word) with brevity – with a little bit of good organization and audience sensitivity thrown in. In fact, a straightforward organization of your email is a good place to start. Always start with your ask and/or an introduction to your attachment. That is, lead (pronounce it “leed” in this sentence!) with your question or request or – if you are responding to another email – lead with your response and/or a brief phrase/sentence that describes your attachment.

Recently, a friend of mine was awkwardly caught up in a job-referral situation in which she wanted to ask a complete stranger for a job interview, having been referred to that stranger by a manager who had rejected her job application at his company (though he did so with great heart and positive feedback). She asked me to look at her email, which opened with a long complex sentence about her job qualifications. (For an example of a long, complex sentence, look at the first sentence in this paragraph!) She followed that with her question, requesting an interview.

I advised her to start the email with her question (since the email from the mutual acquaintance was attached anyway) and to follow that question with two sentences created from the overly complex sentence she had originally started with. Wallah! She secured the job interview and went on to win the job. Hurray! OK, her success probably can’t be solely attributed to her revised email. But I like to think I helped.

If your opening sentence (with your question/request or response/attachment-description) needs more context, then go ahead and provide it – but in a separate paragraph. You can even label that paragraph with the heading “Background,” “Clarification” or “Additional Information.” Here’s where audience sensitivity comes in. Most of the time, your reader will be interested only in (and read no further than) your ask or response. However, sometimes if – like me – they are overwhelmed with email and might have no clue what you are talking about, they need to understand the circumstances that compelled you to write the email. This is particularly true if you are rejecting a proposal or idea.

The idea here is avoid leaving the reader to guess about what you mean (“What the…?”) – or to guess about where you stand. Give him/her another sentence or three (depending on the situation) that provides some context for your opening phrase/sentence. Keep it brief, but be sensitive.

Example: How about lunch on Friday? I have news to share!

Response: Can we push to Monday? Have a big project due 1pm Friday.

While this simple exchange would have been fine minus the second sentences in each, the expanded versions let each recipient know that the relationship is valued (well, relatively speaking). Plus it sets up at least two topics of conversation for the ensuing lunch.

Which brings me to the fact that I am very hungry. OK, too much information – including too much information in an email – is never a good thing. So always circle back to the previous rules – be polite and, above all, be professional. No need for my email pals to know that my stomach is grumbling. I’ll spare them (but not you!) that detail.

Before I go on to my dinner (and sipping wine from a crystal decanter!), I’ll remind you that I have one more business email rule to define – Follow up!

5 Christmas Mondegreens

Merry Christmas, all!

Interrupting the flow of my email rules to bring you my five favorite Christmas song mondegreens.

What is a mondegreen? The term refers to misheard words in a song. According to Leanne Italie of the Associated Press, who interviewed expert Grant Barrett, the word “mondegreen” arose from a 1954 Harper’s Magazine column written by Sylvia Wright. Wright discovered that for years she had misheard (and mis-repeated) the first stanza of the Scottish ballad “The Bonnie Earl o’ Moray.”

The original line from the ballad: “They have slain the Earl of Moray, and laid him on the green.”

What Ms. Wright heard: “They have slain the Earl of Moray, and the Lady Mondegreen.”

Christmas songs, especially as sung by children, are ripe for mondegreens. Here are my five favorites (in English).

1. From ‘Silent Night’ – “…sleep in heavenly peas…”

2. From ‘The Twelve Days of Christmas’ – “…6 geezers laying…”

3. Also from ‘The Twelve Days of Christmas’ – “…9 lazy Hansens…” (instead of “ladies dancing”)

4. From ‘Santa Claus Is Comin to Town’ – “…making a list, of chicken and rice…”

5. From ‘Winter Wonderland’ – “Later on milk and spiders, as we dream by the fire.” (instead of “Later on we’ll conspire…”)

Do you have some favorite Christmas song mondegreens? Please share!

4 Rules for Business Email – Rule #2

As a memory jog, here again are my 4 rules (guidelines) of business email etiquette:

  1. Be Polite
  2. Be Professional
  3. Be Clear
  4. Follow up! (which is an outcome, really, of the first three)

When I wrote about the first rule of business email – Be Polite – I suggested that you avoid email wars by requesting the use of a different communication channel (phone call, face-to-face meeting, facilitated meeting, water pistols at midnight, whatever). But if you absolutely, have to respond by email, please, please remember that you are responding to a human being, not a machine. Most human beings these days – at least the ones I know – are doing the best they can while facing tremendous personal and/or professional challenges. So please remember that.

And if you can’t remember that (really? It’s so hard?), then remember that nasty grams can live forever on someone’s hard disk drive. So be neutral, be sensitive, be smart and above all, be professional.

And that is our second rule of business email – Be Professional.

Email gurus Silberman and Johnson both remind us to watch the tone of our emails. Tone is a tricky thing. But believe it or not, it’s easier to moderate the tone of a written communication than it is sometimes to moderate the tone of our voice. (You can test this next time your cube neighbor douses you with a water pistol – how high and loud is your voice as you supposedly laugh it off?)

To moderate the tone of your emails, choose neutral words in place of more highly charged words. For example, refer to “status,” “open issues,” and “concerns,” not “debacles,” “problems,” or “mistakes.” While you might consider a shifting deadline to be an “issue,” it’s probably better not to refer to it as “missed” or “failed,” unless those words are used officially by your company or are generated by a software application – and you have your attorney sitting right next to you (holding a water pistol). People do take these labels personally, and you don’t want to wade into an inter-departmental (or inter-company) conflict unnecessarily.

toe-water

Pushing into controversy myself a bit here (cue toe-in-water image), I’ll say that part of being professional is being sensitive to the person who was concerned enough about a topic to actually send you an email, especially if that someone is lower on the food chain than you. Being tough or clever or “above the fray” doesn’t always win the day; being appreciative and helpful can have more lasting effects (and remember, the email sender might not always be lower on the food chain).

(Note that I am not going to use the American idiom about catching flies with honey here, because, well, it’s gross and, besides, I’ve already used the term “food chain.”)

You know this, because you know it’s true in “real life,” too. I was reminded of this recently when I attended an evening public meeting in my community. Four professionals had formed a panel discussion on a specific topic. (I’ll be neutral here and not name the topic.) Toward the end of the evening, a woman in the audience stood up and asked specifically for help for her child. She was obviously emotional (though not overly so) but very sincere in her request. Not one of the panel members responded. Yes, you read that correctly, not even one.

Finally (to the relief of everyone), another professional in the audience stood up and offered to talk with her after the meeting. (At the same time, he acknowledged that he wasn’t sure that he was the best person to help her.)

How hard was that? Which one of the six people involved in this situation was the most professional, in your opinion?

OK, now I’ll take my toe out of the water, foot out of my mouth, water pistol away from my head, whatever, and talk about one last pet peeve about professionalism in business email. And that has to do with loooooooong email chains – the kind that cross weeks and even months on the calendar – or emails with multiple or hefty attachments. For the love of Mike, people, keep the context but ditch the heft! Mike, by the way, is the poor IT guy responsible for your company’s overtaxed email server.

So the last sub-rule is about professionalism when responding to a business email that’s been circulated through half the world: Be smart. Before you hit Reply All, make sure that all of the right people are on the distribution list; then delete and summarize any of the simple intervening replies (say, “the following people on the distribution list have already agreed”; then list them) and keep the original email as close on the page to your response as possible. Believe me, people will thank you (including Mike).

And I will thank you to keep reading my blogs on email etiquette (smooth, eh?). The next topic is business email Rule #3 – Be Clear.