DEV Community

Rickard Collander
Rickard Collander

Posted on Originally published at supportifier.se

How to Write a Help Article That Actually Resolves the Ticket

#documentation #writing #ux #customerservice

A template for docs that work for customers, agents and the chatbot that answers from them

A help article that works answers a single question, phrased the way the customer asks it, gives the answer in the first sentence and then the steps, the exceptions and what the customer needs at hand. It is written in plain language without internal terms, and tested by having someone outside the team resolve the ticket with only the article. The same text then serves the help centre, the chatbot and the agent.

Most help centres have articles. Fewer have articles that resolve tickets. The difference shows in the inbox: the customer read the article on returns, couldn't tell whether it applied to a sale item, and wrote an email. If you write or approve support docs, this is a template for them, built on what research on reading on screens and Swedish plain-language practice say works.

Why do help articles resolve so few tickets?

Because they are written from the company's side, about the product, while the customer is looking for an answer to their question. According to a Gartner survey from 2024, only 14 percent of customer service issues are fully resolved in self-service, and that includes many issues customers themselves describe as simple. The customer starts in the help centre, finds an article that almost answers, and makes contact anyway.

How people read on screens explains part of it. Nielsen Norman Group found in its classic study that 79 percent of test users always scanned a new page, and only 16 percent read word by word. The same study measured what helped:

  • concise text improved usability by 58 percent
  • scannable layout by 47 percent
  • objective language by 27 percent
  • all three together: 124 percent

A help article that opens with two paragraphs of background before the answer is written for a reader who does not exist.

Which question does the article answer?

One, and it should be in the heading, in the customer's words. "Can I exchange for another size instead of returning?" is an article. "Returns and exchanges" is a category, and an article with that heading forces the customer to read everything to find their part.

Three consequences:

  • More, shorter articles. Ten questions about returns become ten articles, not one long one. The customer lands in the right place straight away, and a chatbot answering from the articles gets a clear answer to fetch instead of a paragraph from a long text.
  • Headings written the way customers search. Read the questions that actually arrive in the inbox and the chat, and use their words. Supportifier has a separate guide on finding unanswered questions through knowledge gaps.
  • Answer first. The first sentence after the heading is the answer, short and without caveats. Exceptions come afterwards.

How should the article be structured?

In a fixed order, so the customer and the chatbot find the same thing in the same place every time. Six parts; not every article needs all six:

Part What it contains Example for "Can I exchange for another size?"
Heading The customer's question Can I exchange for another size instead of returning?
Short answer One or two sentences answering the question Yes, within 30 days and free of charge. The exchange is done as a return plus a new order.
Steps Numbered list, one step per line 1. Register the return under My pages. 2. Place a new order for the right size. 3. Drop the parcel at the pickup point.
Exceptions When the answer does not apply Sale items cannot be exchanged. Underwear and swimwear cannot be returned if the packaging is opened.
Have at hand What the customer needs to complete the steps The order number and the email address from the order.
Contact us when The situation where the article is not enough If the item is damaged, or if more than 30 days have passed.

The order is deliberate:

  • Short answer first, so the person who only scans still gets the answer.
  • Steps as a numbered list, the format that works when the customer is doing the thing with a phone in hand.
  • Exceptions after the steps, not before, since they apply to a minority.
  • "Contact us when" last, to steer the tickets that still need a person to the right channel with the right details.

It is the same structure that makes an article easier for Google and AI assistants to find: what helps the customer helps the search engine.

What language should you write in?

Plain language: the most important thing first, short sentences, everyday words, and addressing the reader as "you". That is not a matter of style but a proven method. The Institute for Language and Folklore, responsible for plain-language work in Sweden, sums it up: start with what matters most to the reader, write short and informative headings that summarise the content, avoid long and complicated sentences, and choose everyday words over technical terms.

For a help article, in practice:

  1. Write "you" and "we". "You register the return under My pages", not "Returns are registered by the customer in the customer portal".
  2. One sentence, one thing. Two clauses joined by "and" are usually two sentences.
  3. Use the customer's words. The customer says "exchange", not "redelivery", and "cancel", not "withdraw from the contract". Put the technical term in brackets if it's needed.
  4. Be concrete. "Within 30 days of receiving the parcel", not "within the applicable return period".
  5. Remove the caveats. "Normally", "as a rule" and "usually" make the answer unusable. If something doesn't always apply, write the exception instead.

Google's guidance on helpful content points the same way: the text should give the reader enough to reach their goal, be written by someone who knows the subject, and not exist to fill space. A help article written for the customer meets those requirements by itself.

What should you leave out?

Everything that doesn't help the customer resolve that particular question: internal terms, sales copy, history, and things only the agent needs to know.

The most common mistake is mixing the customer's text with the team's. The agent needs to know that size exchanges are booked as "RB" in the order system and that exceptions are approved by the team lead; the customer does not. In a knowledge base with internal fields, those notes sit on the same article but are shown only to the team, so the customer's text stays clean without splitting the knowledge.

Three more things that should go:

  • Dates and campaigns that expire. "Free shipping in September" in an article about deliveries is wrong in October. Put time-limited terms in their own article with a best-before date, or write about the rule instead of the campaign.
  • Apologies and explanations. "Due to high demand" belongs in a status notice, not in an article that should last a year.
  • Several topics. When an article needs a subheading that isn't a step, it's usually two articles.

How do you know the article works?

Have someone who doesn't know the answer resolve the ticket with only the article, then follow whether customers still get in touch about the same thing. Ask a colleague outside customer service to exchange the size on a test order with the article as their only help. Where they stop, a step or a word is missing.

After publication, watch three signals:

  1. Contacts after reading. Customers who read the article and still write in about the same question. Read what they ask; that's the missing sentence.
  2. Comments and ratings. Gartner recommends that both customers and agents should be able to flag content that doesn't work, with an ongoing process to improve it. A "Was this article helpful?" button with free text is enough to start.
  3. The chatbot's answers. Ask the bot the question and read what it answers from the article. If it gets it wrong, or adds something that isn't there, the article is unclear on that point. An article with the answer first and the exceptions clearly stated is the one the bot can reproduce correctly.

What to do

  1. Pick the five questions that arrive most often and have the same answer for every customer. Write them in the customer's words as headings.
  2. Fill in the template for each: short answer, steps, exceptions, have at hand, contact us when. Skip parts that aren't needed.
  3. Read through against the plain-language rules: "you", short sentences, everyday words, no caveats, no internal terms.
  4. Have the subject owner check that the exceptions are correct, and a colleague outside the team test that the steps can be followed.
  5. Publish and connect: the article in the help centre, as source material for the chat and as a suggested reply in the inbox. In Supportifier it is one and the same article that is used in all three.
  6. Follow up after four weeks: contacts about the same question, flags, and what the bot answers. Rewrite the sentence that's missing.

FAQ

How long should a help article be?
As short as the question allows. A question with one answer and three steps fits in under a hundred words, and that's usually the right length. If the article grows longer than one screen on a phone, check whether it answers more than one question. If it does, split it.

Do we need screenshots?
Only when a step is hard to describe in words, for example where a button sits in an app. A screenshot becomes wrong as soon as the interface changes, and a chatbot can't reproduce it. Write the steps in text first so the article works without the image, add the image as support where needed, and give it descriptive alt text.

How do we write for both the customer and the chatbot?
By writing for the customer. A chatbot answering from the help centre fetches the passage that best matches the question, so an article with the question in the heading, the answer in the first sentence and the exceptions clearly stated gives the bot the right material. What makes the bot uncertain is the same thing that confuses the customer: caveats, several topics in one text, and answers that assume something not stated in the article.

Should we translate the articles?
Yes, if you have customers who write in another language, but translate the whole template, not just the short answer. The exceptions and "contact us when" are what most often get lost in translation, and that's where the tickets arise. Have the subject owner review the translated version too, and keep the versions linked so a change in one shows up as a task for the other.

Sources

Originally published on the Supportifier blog: How to write a help article that resolves the ticket.

Top comments (0)