“The site threw a fatal error because a plugin update called a deprecated function that was removed under PHP 8.” Every word of that is accurate, and to most clients it is noise. What they hear is: something broke, it sounds complicated, and it might be someone’s fault.
Clients do not need fewer facts. They need the facts in an order that answers their questions: what happened to my business, is it fixed, what does it cost me, and what do you need me to decide. This post is a working method for turning technical WordPress problems into that kind of explanation, with before-and-after examples and wording you can borrow for calls, emails and reports.
Start from the client’s four questions
Whatever the problem, a non-technical client is trying to answer the same few things. Build every explanation around them, in this order:
- What did it affect? In business terms: visitors could not see the site, orders stopped, emails were not delivered, pages loaded slowly.
- Is it under control? Fixed, being fixed, or waiting on something.
- Why did it happen? One or two plain sentences. Detail available on request.
- What happens next, and do I need to do anything? A decision, an approval, a cost, or nothing at all.
Developers naturally explain in the opposite order, starting with the cause, because that is how they found the problem. Flipping the order is most of the work.
Before and after
Before: “WooCommerce’s latest release conflicted with the custom snippet in functions.php that modifies the checkout fields hook, which caused a fatal error on the checkout endpoint. I’ve patched the snippet and cleared the object cache.”
After: “For about an hour this morning, customers could not complete checkout. It is fixed now and orders are coming through again. The cause was a recent update to your shop software clashing with a small piece of custom code added when the site was built. We have rewritten that code so it works with the new version. Nothing is needed from you, but it would be worth checking whether any customers contacted you about a failed order this morning.”
The second version is longer, but every sentence answers a question the client actually has.
A translation table for common WordPress problems
Keep a shared list like this so everyone on your team describes the same problems the same way.
| What the developer says | What the client needs to hear |
|---|---|
| Plugin conflict | Two add-ons on the site are trying to do overlapping jobs and getting in each other’s way. |
| PHP version upgrade | The host is updating the language the site runs on. Older parts of the site may need adjusting to keep working. |
| Database connection error | The site cannot reach the place where all its content is stored, so it cannot show any pages. |
| Caching issue | The site is showing a saved older copy of the page instead of the new one. |
| DNS propagation | The internet’s address book is still updating to point your domain at the new location. Some people see the new site sooner than others. |
| SSL certificate expired | The security certificate that lets browsers trust the site has run out, so browsers are warning visitors away. |
| Email deliverability / SPF / DKIM | Emails from the site are not carrying the identification that inboxes expect, so they are being filtered or rejected. |
| Malware / injected code | Someone placed harmful code on the site without permission. We need to remove it and close the way in. |
| Abandoned plugin | One add-on is no longer being updated by its makers, which makes it a growing risk. |
| Server resource limits | The hosting plan does not have enough capacity for what the site is now being asked to do. |
None of these is perfectly precise, and that is fine. The aim is a correct mental picture, not a technical education.
Analogies: useful, in small doses
A good analogy makes a problem click. A bad one misleads the client or sounds patronising. Some rules that help:
- Use one analogy per explanation, not three. Mixing a car engine, a house and a library in one email confuses more than it clarifies.
- Choose ones that point to the right action. Comparing updates to servicing a car works because it leads to “regular maintenance prevents bigger repairs”.
- Avoid analogies that suggest blame or panic. “Your site is like a house with the front door wide open” may be true of an outdated plugin, but it alarms more than it informs. “One lock on the building is out of date and needs replacing” carries the same point more calmly.
- Drop the analogy once the client understands. Do not keep stretching it to cover details it does not fit.
Words that cause trouble
Some words feel harmless to a developer and land badly with a client.
- “Just”. “It just needed a small fix” can make the client wonder why they are being billed. “It needed a targeted fix” is better.
- “Should”. “It should be fine now” sounds uncertain. Say what you checked: “We tested the form and the booking page, and both are working.”
- “Hacked” when you are not sure. Only use it when you have evidence. Otherwise say “we found unexpected code and are investigating”.
- “Your developer did this badly”. Even when inherited code is poor, criticism of the previous team makes the client feel foolish for hiring them. Describe the risk and the fix instead.
- Acronyms without a gloss. If you must use one, explain it once in passing: “the site’s security certificate (SSL)”.
How much detail is the right amount?
Different clients want different depths. A founder of a small shop usually wants the business effect and the next step. A technical marketing lead may want to know which plugin and why. Offer the short version first and make the long version available:
“That is the short version. If it is useful, I can send the technical detail for your records or for anyone on your team who looks after the site.”
Note the client’s preference in their record so the next explanation starts at the right level.
Explaining problems that need a decision
The hardest explanations are the ones that end with a request: approve a cost, accept a risk, or choose between options. Structure them so the choice is clear.
A template for decision emails
- What we found, in one or two sentences.
- Why it matters to the business.
- The options, usually two or three, each with what it involves and what it leaves undone.
- What you recommend and why, in one sentence.
- What you need from the client, and by when, if timing matters.
Example: “Your host is retiring the older version of the software your site runs on. Several parts of your site are not yet compatible with the newer version and would stop working. We can either test and update those parts now, before the host makes the switch, or wait and fix whatever breaks afterwards. We recommend testing now: it avoids an unplanned outage and lets us choose a quiet time. If you are happy with that, reply to approve and we will send a quote and a suggested date.”
If you want the technical side of that particular conversation, our explainer on what breaks when WordPress moves to a newer PHP version is a good reference.
Written explanations last longer than calls
Calls are good for reassurance; writing is better for clarity. After any significant problem, follow the call with a short written summary. It gives the client something to forward to a manager, and it gives you a record of what was agreed.
The same habits belong in your monthly reports. A line like “updated 14 plugins” tells the client little. “Applied security and compatibility updates to the add-ons your site uses, and tested the contact form and shop afterwards” tells them what they paid for. Reports written in that voice are the ones clients actually read.
When the client is upset
An anxious or angry client is not looking for a better analogy. Lead with acknowledgement and status, then explanation:
- Acknowledge the effect: “I know this cost you enquiries this morning.”
- Give the status: “It is working again, and here is what we checked.”
- Offer the explanation briefly, and the follow-up in writing.
- Do not argue about fault on the same call. Come back to it calmly in the written summary if it matters.
For the sequence of messages during an outage itself, our guide on what to tell a client when their site goes down covers each step.
Helping clients explain problems to you
Communication runs both ways. Clients who describe problems well save hours. A short guide you can share with them, covering what to include and how to take a useful screenshot, pays off quickly; our article on how to report a website problem to a developer can be passed straight to clients or adapted.
When a partner writes the technical notes
If an outside developer fixes problems for you, ask them for two things in every handover note: the technical detail for your records, and a plain-language summary you can adapt for the client. That way your team edits for tone rather than translating from scratch, and the client hears a consistent voice from your agency. It is one of the small habits that makes outsourcing work smoothly, alongside the others in our overview of outsourcing WordPress for agencies.
If your reports are where the plain-language explanations most often fall short, our unbranded client reports are written in client-ready language for you to send as your own, and we would be glad to show you a sample layout.
Next in this series: Recurring Revenue for a Web Agency: Beyond Projects
