Dear [Firstname] at [Company] — Drop the Fake Friend Act

Dear [Firstname] at [Company],

Today, you sent me a message that pushed me over the edge after a blogging hiatus that has been far longer than I like to think about.

Subject line: “Was it something we did?”

Body: I have no idea, do you honestly think I opened that? The message was clearly based on some pre-configured logic catching users who signed up for your service eons ago, then stopped using it. I’ve tested a lot of services for work in the past year, most of which I’ve left behind. It was less something you did and more something we didn’t.

But why oh why would you think it’s appropriate, funny, cute, or *shudder* engaging to sound like a needy ex-partner?

Overly Attached Girlfriend: In ur mailbox, begging for ur attention. Also known as [Firstname] at [Company].


Today’s overly attached subject line was not an isolated incident, of course. Just a handful of fairly recent examples from my inbox:

  • A subject line welcoming me to the [service] family, message starting with “Hey, you’re awesome!!”
  • A “thank you for upgrading to a pro account” message signed “Your friends at [company]”
  • A service sign-up response with the subject line “Friend, welcome to [service]”

All sent, of course, by [Firstname] at [Company] — a trick so ubiquitous it no longer stands out in the least in the increasingly crowded Promos section of my Google Inbox.

Most of my personal and even work messages now go through chat, but everyone and their grandmother’s company is bombarding me with email as a lead or customer — “drip campaigns”, auto-responders and quasi-personal messages intended to steer me along the journey to conversion from lead to customer, and from customer to evangelist.

But I must admit, [Firstname] at [Company], it’s increasingly rare that I even open your messages. And you just seem to get chummier and chummier.

I expect your company does a lot of A/B testing, so please do tell me: Does the bromance lingo actually work on a majority of your targets? Because to me, really, very little could be more alienating.

It may have to do with regional culture, it may have to do with being too old to be part of the main target group for Every Marketing Campaign on Earth — millennials — but honestly, even a few millennials have mortgages and PTA duties and the odd gray hair and cellulite at this point, are you really sure they don’t prefer being talked to like grownups?

And for those who would be on board with the “you’re awesome double exclamation mark” thing amongst actual friends, are you sure they don’t see you as something of a wannabe, or like the awkward parent who picked up a little bit of slang 10 years ago and still thinks it’s the bomb?

[Firstname] at [Company], are you sure you're not sounding a little like Vanilla Ice: Oh, I'm just coolin?

Why Can’t We Be Friends?

One of the reasons I’m ranting about this is that since going from tech writer at a massive corporation to information architect at a small company where everyone wears a rich selection of hats, technical marketing for the business-to-business market is a form of communication I’ve suddenly had to care about. I’ve been reading up. And I’ve despaired, discovering that “landing pages” does not actually describe pages for visitors to land on, but pages for businesses to land people’s email addresses.

After reading a few more marketing blog posts than was clearly good for me, a bit too much of it started to make sense. Then, thankfully, I was lucky enough to spend most of last week at the Information Architecture Summit, an amazing conference about IA and user experience, whose theme this year was inclusion and “a broader panorama”. What happens when we put people at the center, when we design inclusive experiences, when we genuinely care about the humanity of every user, visitor, customer? And I came back reassured that what doesn’t happen is shiny happy auto-responders holding hands. (I learned a bunch of other stuff, too. There will be more blogging.)

So no, it’s not that I don’t think that businesses can have interesting information to share with (potential) customers by automated email, or that customers and vendors cannot have a friendly tone when they know each other — on the contrary. But here’s the thing, [Firstname] at [Company], the two are entirely separate things. And because you are not a person, but a set of merging and mailing rules, that is something you will never understand.

And that is why we can’t be friends. So can you please drop the act?

Not exactly yours,


Link Roundup: APIs and Fine Manuals

Still wrestling with my next post on error messages. Meanwhile, I’m sharing some excellent links on technical communications I’ve happened upon lately.

The unbearable annoyance of error messages

Error messages are a constant source of frustration to users of all skill levels. A recent example is Don Norman’s rant Error Message Are Evil (sic) on LinkedIn, where he insists that error messages must start collaborating with the users, and that software needs to become better at anticipating and accommodating actual user behavior. As someone who is often tasked with the writing and rewriting of error messages, it’s hard not to agree.

Error messages are a constant source of frustration (Image title: 138/365 Frustrated)
(Image by martinak15 on Flickr)

Here are the three most common unhelpful types of error messages that I know of, and what makes them unbearably annoying to me.

1. Written for the developers: Object reference not set to an instance of an object

Of all error messages that should not go out to end users, this example is probably my least favorite. Someone really should just change the standard nullpointerexception error with something more readable to a user, once and for all. “Developer malfunction”, perhaps. I kid, but only just. And there are many more messages that follow a similar logic.

All too often, internal error messages trickle out to users from frameworks, APIs, or deep dark places in code that nobody every intended to expose. They are usually hardcoded and hold no information that the user can make sense of, or wrap a tiny piece of readable information in noise. Typically, they also use words like “illegal”, making any normal person think a crime has been committed, rather than the use of a character that couldn’t be parsed.

2. Well, duh: Unexpected error

Ohhhh, so you didn’t see this one coming, application? Well, that’s helpful for me as a user to know. And now what?

The literal “Unexpected error” is quite common, but there are tons of messages out there that are at about the same level of helpfulness once you’ve read them. Telling the user at least something they don’t already know is a very basic criterion for an error message. And they probably don’t care whether or not you were expecting it, but they do care whether it will fix itself or requires intervention.

3. Intended to be funny: Well, this is embarrassing

The example is from Firefox being unable to open a page, but Chrome’s “He’s dead, Jim”, or the Twitter whale, are more of the same, and the trend has been spreading, perhaps due to advice like this post from UXmas: The 4 H’s of Writing Error Messages, where “humorous” is one of the H’s, as the author claims it helps diffuse frustration. I disagree–and actually even the UXmas author himself goes on to warn that humor is not appropriate in most actual error situations.

Cutesy, chummy, intended-to-be-funny error messages may serve that purpose the first time the users see them. But error situations have a way of repeating themselves. The tenth time you get to the same error, the funny, “friendly”, conversational error message style is likely to have grown on you much like a fungus. There’s a reason there are tutorials for Getting Rid Of Firefox’s “Well, This Is Embarrassing” Message.

Being helpful is about being respectful to the user. Error messages should be troubleshooting assistants for users, not their pals. An actual pal might buy the user a drink when the operation fails for the 15th time, the error message will still just say the same thing.

Helpful error messages are hard (to write)

Users are annoyed when something fails. We don’t want to feel like we did something wrong, or like we spent our time, money, or both on a product or service that isn’t up to the job.

Writing helpful error messages is hard, but probably one of the best possible uses of a technical communicator’s time. I will share my own concrete advice for helpful error messages in a new post shortly.

Which error messages are most annoying to you? Do you enjoy the use of humor?

Making a list? Check it (at least) twice!

Making a list is a great way to make content accessible and scannable and give readers an overview. Lists are everywhere, and for good reason.

A well-written list can be a quick read, but when making a list, taking some time to properly consider the format and syntax will pay off in clarity and helpfulness for your readers.

Below, I have gathered some advice for writers and editors dealing with lists, based on my own writing and editing experience. If you have other tips or pitfalls on your mind, please share them in the comments!

Tips for making a list summarized: Use the right kind of list, avoid redundancy, and be consistent

Use the right kind of list

It’s easy to think that usage conventions for list types are exactly the kind of thing only writers would care about. If you think that way–I have myself on occasion–then consider this progress screenshot from a WordPress backup plugin that I recently installed:

Screenshot of a message saying DO NOT DO ANY OF THE FOLLOWING and goes on to list in numbered sequence 3 actions not to perform while the installation is ongoing. When making a list, try not to confuse people more than necessary.

Without reading this multiple times, would you feel certain that you were actually not supposed to do anything mentioned in this numbered list? The introduction says one thing, but the choice of list type is communicating something different entirely.

Use an ordered list if you are describing any of the following:

  • a procedure to follow
  • a sequence of events to observe
  • a clearly prioritized order

Some may also prefer alphabetical ordered lists for options where only one may be selected (“Do one of the following: a. b. c. d.”).

If the list is not a sequence, an unordered bullet list is the most common option. However, long bullet lists are not particularly easy to read. For lists that are long and/or include a lot of information in each list item, these two other options are worth considering:

  • description lists (definition lists pre-HTML5) for glossaries, metadata listings, and similar. These tend to be styled in a manner that make them a lot more scannable than bullet lists. See Mozilla Developer Network for a good description and examples.
  • tables. I know, tables are not actually lists, nor do they have the Twitter or Pinterest appeal of a Top 5 list, but for reference-style material, a table provides much better findability and overview than a bullet list.

I like lists, I’m controlling, I like order. I’m difficult on every level. (Sandra Bullock)

Avoid redundancy

List items that start identically, or semi-identically, reduce scannability. Keep in mind that tables of contents are also lists. If you have a table of content that is generated based on your headings, considering each heading a list item is useful.

To ensure list items remain scannable, you can:

  • front load each list item by starting with important keywords that set it apart from other list items rather than something generic , such as “You will need to …” or “For simplicity and ease of use, we have …”.
  • move repetitive phrases outside of the list itself. For example, instead of starting each list item with “how to”, make “how to” part of the introductory phrase that comes before the list.
  • drop any words and expressions that don’t add to the meaning. In most cases, list items don’t need to be complete sentences.

As a bonus, if your writing will be translated, you’ll save money by avoiding redundancy.

Every morning I get up and look through the Forbes list of the richest people in America. If I’m not there, I go to work. (Robert Orben)

Be consistent

In a list, each item should have a similar syntax. This is a pet peeve that probably annoys me as a writer more than most readers, but I have seen plenty of bullet lists that would be confusing for any kind of reader.

Before unleashing a bullet list on the world, read through it starting with the introductory phrase and check that all list items:

  • start in a similar fashion to the others and read as a grammatically correct continuation of the introductory phrase. If the introduction says: “This chapter will tell you how to:”, you cannot have list items starting with “making” or “configuration”.
  • share the same grammatical subject or state their subject clearly. Otherwise you may easily conflate, for example, something done automatically by software with something  users must do themselves, or something the software vendor can do for you upon request. In my experience, this problem is not uncommon in lists of features and software specifications.
  • use similar syntax and punctuation. Mixing questions with statements in the same list will usually not read well. Whether or not to end each list item with a full stop is a style/preference issue. It is also painfully hard to remember and follow up on in a consistent manner.

We like lists because we don’t want to die. (Umberto Eco)

Helpful error messages for fun and profit

Nobody is keen to invest in error messages. And by invest I mean energy, money, man hours … Declare “Our product will excel at failing gracefully”, and you can probably count on your stakeholders to drop off after “excel at failing”.

Grafitti with poster saying

Photo by binturong2 on Flickr

Everybody fails (sometimes)

But every. Product. Fails. Networks happen, unexpected input happens, integrations with other products happen. The real world happens, and what do we do then?

My last post about unhelpful error messages sparked some interesting comments and discussion, on the blog and in the Technical Writer in Action LinkedIn group, including a lot of good points about what fellow tech writers consider to be good qualities in an error message. I said I would follow up my post with a more constructive take, and here it is.

1. Fight the power (push back, fix the code)

Rewriting error messages often runs the risk of being lipstick on the proverbial pig. Sometimes it’s all we can do as writers short term to improve the writing, but we shouldn’t be scared to push back and look at whether the product is behaving as it should in the first place:

  • Could the error be prevented before it happens? For example, improve the UI to prevent users from entering invalid input, highlight required fields, and so on.
  • Is the error displayed to the right users? Misconfiguration in the backend should raise a ticket for whoever configures the backend, rather than cause ugly error messages for the end user who can do nothing about it. Messages that essentially say “Contact your administrator” should rather say “Your administrator has been contacted”.
  • Is one error message enough? One of my most frequent requests is actually more error messages. For users, more messages can actually be a good thing, because they allow us to be more specific. Too often, developers create catchall messages that cover so many scenarios it is close to impossible to give users instructions of any value. A shocking amount of error messages can be paraphrased as: “This, that, or the other may have happened. Try 547 different configuration changes, or wait an hour or two and it may have gone away.” Not helpful.

2. Find out what it means to me (respect the user, be instructive)

Good error messages are respectful of users and their time. Conciseness is a value in and of itself. Users read this stuff to do, they don’t read to learn. For this reason, I find that going into detail on exactly what has happened is often not the best use of screen space and user attention.

For the user to be able to do, the message must be instructive. An instructive message focuses on why the user should care about this message, and either give them reassurance that someone else will fix the problem, or give them the information they need to act themselves. This information needs to be:

  • specific
  • inclusive enough that it doesn’t entirely exclude potential scenarios. Few things are more frustrating than following instructions that turn out to have no relevance.

When working on pop-up messages, I always try to pay attention to the buttons as well, and aim for descriptive action verbs. Users may find having to click “OK” after reading about a critical error downright offensive, and it does not tell them what happens once they have clicked the button, either.

3. Only when I laugh (don’t try for funny)

Final word of advice: don’t try to be cute or funny. I have seen several people insist, after my previous post about humor and error messages, that it’s fun and appropriate if the error isn’t very serious, such as a 404 not found message.

Instead of reiterating my first rant, let me tell you a story:

A few months ago, I visited a newly overhauled website that was boasting about its new backend and look and feel. I tried to use the site search, but clicking on links in my search results repeatedly took me to a “hilarious” new 404. Clearly, some pages had gone missing in their migration to a new platform. These things happen, of course, but “funny” not found pages pretty much assume that the user has clicked on a random rotten link or entered a wrong URL. In my case, I could not find the content that the site’s own search results promised. My frustration was mounting. Spare me the jokes!

Point of the story: it’s hard to predict all the scenarios and situations users will be in when they see our error messages. It is, in fact, about respect. You show it, or you lose it.

That’s what it’s all about

Creating helpful error messages can be very hard, but it’s so worth it. I would say it’s about the best use of a technical communicator’s time I can think of. Troubleshooting is where users tend to get the most frustrated, and better instructions in the product simplify troubleshooting. Less frustration, happier users. And happier users is what we should be all about.

© 2018 Techy Writer

Theme by Anders NorenUp ↑