Release Notes and Demos: How Developers Present Work to People Who Don't Read Diffs

Developers who present their work well get their changes adopted, supported, and trusted, and in the AI era that is where the bottleneck has moved. Release notes should be written per audience, each one stating what changed for that reader, what they do differently, and who to ask. Demos should show the before, the change, and one failure path, and end by asking for a decision. AI can draft both; only the developer knows the impact.

The worst release I have supported in payments was not a defect. The code was correct. The change made the beneficiary name check stricter on outgoing instant payments, exactly as the new Verification of Payee rules required. The release note said: VOP: tighten name match threshold (PAY-2291). Support read it, did not know what it meant, and spent the first morning telling customers their payments were failing because of a system issue. Operations raised an incident. The business asked for a rollback of a regulatory change.

Everything worked except the explanation. When a team ships twice as many changes because an assistant writes half the code, the people who absorb those changes (users, support, operations, integrators, compliance) do not double their capacity. The explanation becomes the constraint. I built Real-World BA Deliverables (20 Templates) because the documents around a release are where most delivery teams improvise, and improvising them is how a correct change turns into an incident.

What is the difference between a commit message, a changelog, and a release note?

They have different readers, so they are different documents.

Artifact	Reader	Answers	Written from
Commit message	Developers, future you	What changed in the code, and why	The diff
Changelog	Developers, integrators	Everything that changed, in order	Commits, often generated
Release note	Each affected audience	What changed for me, what do I do, who do I ask	Pull requests plus impact knowledge

A changelog generated from Conventional Commits (feat:, fix:, feat!: for breaking) is a good source. Tools such as release-please, semantic-release, and git-cliff produce it automatically. It is not a release note, because it cannot say what support should tell a customer.

Who needs a release note, and what does each one need?

Every audience that has to do something differently. Usually four:

• Users need what they will notice, in their terms, and whether they need to act.
• Support needs what customers will ask, the answer to give, and when to escalate.
• Operations needs new alerts, changed runbooks, configuration, and how to roll back.
• Integrating teams and partners need contract changes, breaking changes with dates, and how to test before the date.

Compliance and audit sometimes need a fifth note: which control or regulatory requirement this change implements, with the evidence of testing.

What does the same change look like written for each audience?

Here is the Verification of Payee change written properly:

## Release 2026.39: Payments

### For customers (in-app and help centre)
When you send an instant payment, we now check the recipient's name more
strictly against their bank's records. If the name is close but not exact,
you will see the name the bank holds and can choose to continue or edit.
Nothing changes for payments to saved recipients you have paid before.

### For support
What customers will see: a "close match" screen more often on first-time
recipients, roughly 1 in 12 instead of 1 in 40, based on SIT volumes.
What to say: the check protects them from sending to the wrong account;
they can confirm and continue. Macro: VOP-04.
Escalate if: a customer reports "no match" for a recipient they have paid
before (should not happen; tag VOP-REGRESSION).

### For operations
New metric: vop_close_match_ratio. Alert above 15% for 30 minutes.
Runbook: RB-PAY-17 updated with the threshold rollback (config only,
no deploy: vop.match.threshold back to 0.82).
Dependencies: none new. Scheme endpoint unchanged.

### For integrators (Payments API)
No contract change. The existing matchResult field now returns CLOSE_MATCH
more often. If you treat CLOSE_MATCH as a failure, review that logic before
2026-10-01.

Same change, four readers, four answers. Notice what each section has in common: a concrete behaviour, a number where one exists, an action, and a way out. The support section alone would have prevented that incident.

How do you use AI to draft release notes without shipping AI prose?

Let the assistant do the assembly and do the impact yourself.

Below are the pull request descriptions merged into release 2026.39.
Audiences: customers, support, operations, integrators.

For each audience, draft a section with: what changed in their terms,
what they must do differently, and known risks. Use only facts stated in
the pull requests. Where a section needs information the pull requests do
not contain (numbers, macros, runbook ids, dates), write [NEEDS INPUT: ...]
instead of inventing it. List pull requests that affect no audience.

The [NEEDS INPUT] markers are your checklist. Every one is a fact only the team knows: the expected volume, the support macro, the rollback switch. Fill them, then read every sentence against the diff, because a confident release note that misdescribes a change is worse than no note. This also only works when the pull request descriptions are good, which is one more reason for the template in Code Review When AI Wrote the Diff.

What does a breaking change notice need?

More than a line in the release note, and earlier. For an API or event contract change, the notice includes:

1. The exact change: endpoint, field, enum value, or behaviour, with before and after.
2. Who is affected: named consumers where you know them.
3. The effective date, and the deprecation period before it.
4. What consumers must do, and how to test against the new behaviour before the date (a sandbox, a header, a flag).
5. A contact and a channel for questions.

For HTTP APIs, back the notice with the Deprecation and Sunset response headers so it reaches consumers who never read email. Classifying what is and is not breaking, and assessing consumer impact, is covered in API Versioning and Breaking Changes. Writing the contract documentation that makes these notices easy is the subject of API Documentation from Scratch.

What is a demo for?

A demo exists to let someone decide: accept the story, approve go-live, change direction, or fund the next step. A demo that does not end in a decision is a status update with a screen share, and stakeholders learn to skip those.

The developers whose demos people remember do three things differently: they show the problem before the solution, they show a failure path on purpose, and they say out loud what they need from the room.

How do you structure a ten-minute developer demo?

Five parts. Timings are for a sprint review slot.

Part	Time	What you show	What it proves
Problem	1 min	One sentence, who has the problem, one number	You know why this matters
Before	1 min	The current behaviour or workaround	The change is real
Change	4 min	The new behaviour on realistic data	It works for the actual case
Failure path	2 min	One realistic failure and how the system handles it	It will survive production
Decision	2 min	The specific decision you need, and the options	The meeting has an outcome

The failure path is the most persuasive two minutes in the demo. Showing a payment rejected with a clear reason code and the customer message it produces tells a product owner more about readiness than any happy path. It also tends to surface the question that would otherwise have been asked in production.

How do you prepare so the demo does not fail live?

• Stable environment, prepared data. Seed the exact records you will use. Never demo on data someone else is testing with.
• Script the clicks, not the words. Write the steps; talk naturally.
• Rehearse once, end to end, in the same environment, the day before.
• Keep a recording as a fallback. If the environment falls over, play it and move on.
• Have the evidence one click away: the test run, the log line, the dashboard. When someone asks “how do you know?”, show it.
• Say what is not done. Stakeholders forgive incomplete; they do not forgive surprised.

For technical audiences, such as a partner integration or an architecture review, demo against the API directly with a collection, which is the approach in API Proof of Concept and Demos. The request, the response, and the event on the topic are more convincing to engineers than a user interface.

How does presenting well change a developer’s career?

It makes your work visible in the terms the organisation uses to decide who gets trusted with more. A developer who can explain a change to support, operations, and the business in ten minutes becomes the person invited to the go or no-go decision, the incident review, and the design discussion for the next quarter. That is where the interesting work is decided.

It is also the skill most directly amplified by AI. Drafting notes, slides, and scripts is now fast. The judgment about what to show and what it proves is still yours, and it is what people remember.

The takeaway

When changes are cheap to produce, the explanation becomes the constraint. Write release notes per audience, each with what changed, what to do, and who to ask. Let AI assemble the draft and mark every fact it cannot know, then fill those facts yourself. Give breaking changes their own notice with a date and a way to test. Demo to get a decision: problem, before, change, one failure path, and the ask.

The Verification of Payee release would have been a non-event with a four-section note. That is the return on half an hour of writing.

For templates of the delivery documents around a release, start with Real-World BA Deliverables (20 Templates), and for API contracts and change documentation, API Documentation from Scratch. Browse everything at The Tech BA Toolkit. The full set of skills this fits into is in The Developer’s Job When AI Writes the Code, part of the Developer Analyst hub.

Ahmed is a Senior Technical Business Analyst with 10+ years in banking and payments. He builds practical guides and tools for analysts at The Tech BA Toolkit.

Tags: Software Development, Banking, Career Growth, Release Management, Communication