Explaining technical work to non-technical clients: a practical guide

The hardest writing assignment in an agency isn’t the pitch deck. It’s the weekly email where you have to explain, to a founder who doesn’t code, why two developers spent four days “refactoring the permissions layer” and what they got for it.

Done badly, you get a polite nod, a slightly worried follow-up in Slack, and a quiet erosion of trust. Done well, the founder forwards your update to their board and the renewal conversation gets easier. The difference isn’t talent at writing — it’s four specific translation moves, applied in order.

Move 1: Replace the verb with the outcome

Engineers describe their own work by the verb: refactor, optimize, decouple, extract, migrate. Clients don’t care about the verb. They care about the consequence. Every technical verb in your draft should be followed, within the same sentence, by the consequence in their world.

Before: “This week we refactored the permissions layer.”
After: “We rewrote how the system checks who’s allowed to do what, so that adding enterprise SSO for the Lufthansa account next month becomes a one-day task instead of a two-week one.”

The verb (“refactored”) is still there, softened and demystified (“rewrote how the system checks”). But it’s now joined to an outcome (“adding SSO becomes one day instead of two weeks”) with a real dollar shape behind it (the Lufthansa account).

Move 2: Use their unit, not yours

Engineers think in lines of code, test coverage, p95 latency, bundle size. Clients think in dollars, hours, customer complaints, churn, and deadlines. Translate every technical metric into the unit the client already uses.

• “Reduced p95 latency by 400ms” → “Cut the delay your biggest customer complained about in half.”
• “Upgraded to Postgres 16” → “Moved to a newer version of the database, which unlocks the performance work scheduled for Q3 and removes a licensing risk flagged in last month’s legal review.”
• “Added integration tests for the checkout flow” → “Automated the checks that previously took the QA team a full day to run by hand. The team now gets that day back every release.”

The rule: if the client would need a two-sentence explanation of the metric before they could react to it, replace the metric.

Move 3: Anchor the cost to a decision they made

“This took longer than expected” is a confession. “This took longer than expected because we chose to do X” is a decision log. Clients don’t mind cost overruns when they can see the decision tree. They resent them when the explanation feels retrospective or defensive.

Whenever you’re describing work that cost more than the rough estimate, name the decision that caused the overrun — and, where possible, the decision the client was involved in.

“The webhook integration took 3 days instead of 1 because, when we tested against the real Stripe events, we found the retry logic the team agreed on in the March 4 call would not survive a 10-minute Stripe outage. We extended the retry window, which required the extra 2 days. This is the decision we flagged in the follow-up note the next day.”

The client now sees: the original plan, the real-world surprise, the decision that fixed it, and the paper trail. Trust instead of overrun.

Move 4: Never bury the lede in a list

Status reports love bullet lists. Each bullet is the same visual weight as every other bullet. The client reads the first two, maybe glances at the last, and skips the middle. This means the single most important thing you shipped this week must not be in the list — or if it is, it must be in position one.

The safer structure: one sentence at the top of the email, standing alone, that says the most important thing. Then the bullets, for supporting detail.

Hi Ana — a quick summary for this week.

Checkout conversion is up 4% since the Stripe retry fix went live on Tuesday.

Supporting work this week:
— …

The one-sentence lede does two jobs: it signals what mattered, and it gives the client a line they can copy-paste into their own board update. Both matter.

A worked example

Here’s a real-ish fragment from a commit log, and the two translations.

Raw commits:

• feat(admin): bulk user export as csv
• fix(export): stream large exports to avoid memory spike
• refactor(auth): extract token validation into middleware
• chore(deps): bump convex to 1.34

Bad translation (what an engineer would write):

This week we added bulk user export to the admin panel, fixed a memory issue in the export pipeline, refactored auth token validation into a middleware, and upgraded Convex.

Good translation (what the client can act on):

The Premium tier account team can now pull a full user list in one click instead of requesting it from us — that’s 3 support tickets a week off our backlog, and a faster answer for the sales team. Two smaller pieces of infrastructure work in the background: we made the export safe for large customers (the Acme list crashed the old version), and we reorganised how login tokens are checked so that the SSO feature on the roadmap for May becomes simpler to add.

Same four commits, entirely different report. The second version is what clients save, forward, and renew on.

How commitplain helps

These four moves can be applied by hand — it just takes 30-45 minutes per weekly update once you’re fluent. Most agencies never become fluent because the writing feels like overhead, so they default to the engineer’s voice. commitplain applies all four moves automatically: it reads your real commit log, rewrites each entry in executive language at the tone you choose, and drops the draft into your dashboard for review. You edit one or two phrases, approve, send. The four moves happen by default.