Documenting a Hardware API: The Challenges

In last month’s blog, I summarized some introductory concepts and tools for writing about hardware-related REST APIs, a journey I started myself a little over a year ago. To be honest, though, I didn’t make that journey alone. I have been the content strategist for a group of writers, who came at the challenge from various backgrounds. 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!

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 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 wade into an inter-departmental (or inter-company) conflict unnecessarily.


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?). Next topic is business email Rule #3 – Be Clear.

4 Rules for Business Email – Rule #1

Yes, email is still around, and it is still the main form of official communication between business professionals. I realize that rules on email etiquette have been around as long as email has. Email etiquette guru Lindsay Silberman (author of several Email… manuals) has 25 rules for you to follow, and Dave Johnson of MoneyWatch has 9 “keys” for your pocket. But I think I can easily boil those down a bit more.

To start, we should all make one giant assumption in our 21rst century lives: Nothing you send in email will ever die. (This is borrowed from AIIM’s mantra: Nothing on the Internet ever dies.) Emails can be copied, pasted, forwarded, saved and (Hello, NSA!) archived in large data centers somewhere. I am not saying that you should abandon your free-speech rights at the entrance to the corporate campus, just apply your good-sense filters and “look both ways” before you hit Send.

So really there is one overarching rule here: Don’t be stupid. Goes without saying that in the professional business world, you shouldn’t send obscene, rude, sexist, bigoted or otherwise offensive emails (nothing you wouldn’t want your grandmother or grandchild to see). So I think we can explore email etiquette by looking at only 4 rules – well, guidelines really:


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

In this blog we’ll explore the first rule (guideline) and what it means – Rule One: Be Polite

Be Polite – I know this sounds as though I have turned in to my mother, and oddly, I found myself asking my 87-year-old mother the other night if she had been “polite” during a recent dinner at a neighbor’s home when she didn’t like the food. (The reasons why I asked this are deep and many, but I won’t overshare here.)

Translation to business email:  Respond politely to whatever is put in front of you, even if you don’t like it and, most especially, even if you don’t like the person who put it there. The key here is to respoooooond, even if you simply say, “Thank you for your email. I’m sorry, but I am swamped right now. I’ll respond by noon tomorrow.” In fact, you can even set this message as an automatic response (using your email tool’s out-of-office feature) on days when you need some uninterrupted time at your real job – say, planning your next pirate-ship takeover. It will buy you some work time now – and some think time later. (Please don’t overuse this tip. And please do what you have promised to do – and follow-up!)

The main idea here is to say something that indicates you received the email (and thus convey to the sender that the email is not lost in the ozone somewhere). So thank the communicator, and/or acknowledge the meeting or clarification, and/or respond to the request. It doesn’t take most of us long to type, “Got it! Thanks.” Or “Thanks. I’ll be there.” Or “Thanks. I’ll discuss this with the team, and get back to you on N-day.” (Where N=the day you follow-up. More on follow-up with Rule 4, topic of a future blog.)

If the email you’ve received is itself impolite or contains provocative or otherwise unpalatable notions, rather than start an email war with cannons blaring, use your email response to set up another communication channel. You can always write, “May we talk offline about this?” to set up anything from a hallway conversation to a conference call. Or – and here’s a unique idea – take the initiative and pick up the phone to call the sender. (If it makes you feel better, you can throw in a pirate’s “Aaaaargh” somewhere in the conversation…see if they notice.)

One last note: It goes without saying here (again!) that you don’t always have to respond to every email. For instance, you do not have to respond to automated emails, or all-hands emails, or a similar widely distributed email. Use your good judgment (or your mother’s good judgment, whichever best applies).

Next blog – Rule #2 – Be Professional