How to create useful release notes

You ship an update to your custom FileMaker system on a Friday afternoon. Monday morning, three people email the same question: "What changed? Nothing works the way it did." The release note that went out said "Bug fixes and improvements" — technically true, completely useless.

This happens in almost every custom software project, whether it's a FileMaker solution, a connector built with FmBetterforms, or an AI layer added through something like Klai. The update itself might be solid. The communication around it is what breaks trust. This article shows you how to write release notes that actually get read, understood, and acted on — by developers, managers, and end users alike.

What are release notes actually for?

Release notes are not changelogs for developers. A changelog is a technical record — commit messages, ticket numbers, internal jargon. A release note is a message to a human who has a job to do and needs to know if this update changes how they do it.

Good release notes answer three questions for the reader, in this order:

1. Does this affect me? (relevant or not)
2. What exactly changed, in plain language?
3. Do I need to do anything? (retrain staff, re-check a report, update a bookmark, nothing)

If your release note doesn't let a busy office manager answer those three questions in under 30 seconds, it isn't doing its job — no matter how detailed it is.

Who is actually reading your release notes?

In a typical custom software setup you have at least three audiences, and one note rarely serves all of them well:

• End users — the invoice clerk, the warehouse planner, the sales rep. They want to know: did a button move, did a field disappear, is there a new required step before they can save an order?
• Managers and business owners — they want to know: did this fix the problem we asked for, is there any risk, do we need to inform customers or staff?
• Developers and IT managers — internal or external — they want technical detail: which script changed, which API endpoint was touched, which table got a new field, whether a FmBetterforms layout or a Klai prompt configuration was affected.

The fix isn't one giant note. It's one release, written once, but structured in layers so each audience can stop reading once they have what they need.

What does a genuinely useful release note look like?

Here's a structure that works well for FileMaker-based systems and connected ERP/API environments, based on what actually gets read in practice:

1. A one-line summary in plain business language. Not "Refactored order validation script." Instead: "Orders under €50 no longer require manager approval before shipping."

2. Why it changed (one sentence). This single sentence prevents 80% of "why did this change?" support tickets. Example: "This was slowing down small repeat orders — approval is now only required above €50."

3. What the user will notice. Be concrete. Not "the approval workflow was updated" but "the 'Send for Approval' button is now hidden on orders under €50; they go straight to 'Ready to Ship'."

4. Any action required. Example: "No action needed" or "Warehouse staff: please refresh your FileMaker Go app before Monday's shift."

5. Technical detail, collapsed or separated. For developers and IT managers: which script, layout, table, or integration changed. If you use Klai for AI-assisted features, note which model, prompt, or automation rule changed — AI behavior can shift subtly between versions, and that's exactly the kind of thing that causes confused support calls three weeks later if it isn't documented.

A real example: what a bad note vs. a good note looks like

Bad: "v4.3 — Fixed bugs in invoicing module, updated API connector."

Good:

Invoicing: Credit notes now show the original invoice number. Why: Accounting couldn't match credit notes back to invoices in Exact Online. What you'll notice: Every credit note PDF now has "Ref: INV-2024-0182" printed under the total. Action needed: None — this applies automatically to new credit notes. Technical: Updated the CreateCreditNote script and the Exact Online API mapping to pass the source invoice ID.

The second version takes maybe 90 extra seconds to write. It saves hours of support conversations, because nobody has to ask what "fixed bugs" means.

[[IMAGE:right|Release note split into user summary and technical detail layers]]

How detailed should technical release notes be?

For the developer/IT layer, be specific enough that another developer — or you, six months from now — can understand the change without re-reading the code. Good technical notes name:

• The specific script, layout, table, or field affected.

• Whether it's a schema change (new field, new table, changed relationship) versus a script-only change — schema changes matter far more for backups and rollback planning.

• Any external system touched: which API endpoint, which webhook, which integration platform.

• For AI-assisted features (e.g. via Klai): which prompt, model version, or trigger condition changed, since AI output isn't always deterministic and a small config change can meaningfully alter results.

• Whether the change is backward-compatible or requires a coordinated deployment (e.g. server and client update together).

This technical layer is also what makes a system transferable — if a new developer ever takes over the project, a clear technical changelog is often the fastest way for them to understand how the system evolved and why certain decisions were made. That's a core theme in our broader piece on how to make custom business software reliable and transferable.

When should release notes be written — and by whom?

A common mistake is writing release notes at the very end, in a rush, right before deployment. By then, the developer has moved on mentally and writes something vague just to tick the box.

Better approach:

1. Write the business-facing summary when the ticket or feature request is created — the "why" is freshest at that point, often straight from the person who requested it.
2. Update it during development if the actual implementation differs from the plan (it often does).
3. Have someone outside the dev team review the plain-language part before release — a project manager, office manager, or even a non-technical colleague. If they can't understand it, end users won't either.
4. Publish the technical detail alongside, not instead of, the plain-language version.

Where should release notes live?

For small internal FileMaker systems, a simple shared document or an internal wiki page is often enough. For larger or multi-client systems, consider:

• A dedicated "What's New" layout inside the FileMaker solution itself, shown on login after an update.
• A changelog page linked from your support or intranet portal.
• An email digest for managers, summarizing only the business-facing points, sent monthly rather than per release, so people aren't fatigued by every small patch.

Whatever you choose, consistency matters more than the tool. A release note format that changes every time trains readers to stop reading them.

Checklist: is this release note actually useful?

• Does the first line make sense to someone with zero technical background?
• Does it explain why, not just what?
• Does it say clearly whether the reader needs to do anything?
• Is technical detail present but separated, not mixed into the plain-language summary?
• Would this note still make sense to someone reading it eight months from now with no other context?
• Has anyone outside the development team reviewed the wording before it went out?

FAQ

Do release notes matter for small internal tools used by only a handful of people? Yes — arguably more, because there's no formal support desk to absorb confusion. A two-line note in a shared chat can prevent a wasted phone call.

Should every single update get a release note, even tiny fixes? Group minor, invisible fixes (typo corrections, performance tweaks with no visible effect) into a short "minor improvements" line. Reserve full-detail notes for anything a user or manager would actually notice.

What about AI-driven features — do those need different release notes? Yes. Because AI-assisted behavior (via tools like Klai) can shift with a model update or prompt tweak even without a code change, it's worth explicitly noting when AI-related configuration changes, even if the interface looks identical — otherwise "it's acting differently" becomes very hard to trace back later.

Who should own writing release notes on a custom software project? Ideally the developer drafts the technical core, but a project owner or manager reviews and simplifies the business-facing summary. Neither role alone usually produces a note that serves everyone.

Release notes are a small habit with an outsized effect on how much people trust a custom system over time. If your team is rebuilding that habit from scratch, or rethinking how updates, documentation, and handovers work across a FileMaker solution, an ERP integration, or an AI-assisted workflow, Loggix can help map out a practical documentation and release process alongside the technical work — so the system stays not just functional, but genuinely understandable to whoever needs to run it next.