Writing for the support team

Every Tuesday this spring I sat with Karim for an hour and wrote help-centre articles. We got through 23 by the end of May. I went in thinking that my job was to make the sentences shorter. It turned out the sentences were rarely the problem. The problem was that the article started in the wrong place.

Support writes from the inside of the product. An article called “Changing your payment method” began, in its old version, with a paragraph on how payment methods are stored and why cards expire. All true, and interesting to the person who built it. The reader had a declined card and a client waiting, and they scrolled past the paragraph to look for a button.

Karim’s rule, which he took from years of reading tickets, is that the reader arrives with a task and a mild panic. Ours had one question running in their head, which he wrote on a sticky note and put on my monitor:

I’m in the middle of something. What do I click?

We tested every article against that note. If the first screen of text did not tell somebody what to click, we moved things until it did. Background went to the bottom, under a line saying “Why this works this way”. About half of it Karim then cut, since nobody had asked for it in the two years he had been answering tickets.

The second thing was vocabulary. The product says “workspace” in the menu, “organisation” on the billing page and “account” in three emails. Customers say “my company” or, sometimes, “the login”. We could not fix the product in an hour on a Tuesday, so we agreed on a rule for the articles: use the word that is on the screen, exactly, in the same capitals, and say it once in the customer’s words next to it. “Open Settings, then Organisation (the page with your company name).” It looks clumsy for a day and then stops looking like anything.

The third thing was length. I wanted to cut. Karim wanted to keep the troubleshooting steps, and he was right, because the steps are what people use on the second visit, when the first fix has failed. We settled on a shape that I have used since in other writing:

1. One sentence that says what the article will let you do.
2. The steps, numbered, each one a single action.
3. What you should see when it worked.
4. What to do if you do not see it, with a link to contact support.

Step three was Karim’s addition and it was the best one. People do not know whether they are finished. An article that ends on a click leaves them wondering, and wondering becomes a ticket. We added “You should see a green tick next to the new card” to eleven articles, and he watched the related ticket volume for a month. It fell by about a third on the two I checked, though I would not stand behind that number as proof, since June was also a quiet month.

I did lose a few arguments. I wanted to take out “please” and “simply” and “just” everywhere. Karim kept “please” in the contact step, because he said it changes how a frustrated person writes their message. He may well be right. The tone of the incoming tickets does seem calmer, but I only have his word for it, and we have not measured it.

What I take back to my own work is smaller than I expected. I now read the first sentence of anything I write as if I were someone with a declined card, and I check where the button is.