Public-sector release notes: announcing changes to government digital services

Most release notes are written for users who chose the product and can leave it. Government digital services have neither kind of user. Nobody picked your tax-filing service from a comparison table, and nobody unhappy with the benefits portal can switch to a competitor. That changes what release notes are for. In commercial software they are part persuasion, part record. In a public service they are pure stewardship: the institution explaining, on the record, what it changed in a system people are required to use.

This guide is for the people who run those systems — digital service teams in national and local government, civic-tech nonprofits, contractors building agency portals, and the small teams behind court e-filing, school enrollment, permit applications, and benefits screeners. The craft overlaps with writing for non-technical users, but the public sector adds constraints of its own: plain language as a legal obligation, deadlines set by statute rather than sprint planning, and a changelog that may one day be read aloud in an appeal hearing.

Readers who can’t leave

A public-service changelog serves five readers, and only one of them looks like a normal software user.

  • The resident uses the service rarely, under deadline, and often under stress — filing taxes, certifying for unemployment, renewing a license. They don’t follow your updates; they meet your changes mid-task. Notes for them must be findable from the service itself and written in the same plain register as the service.
  • The caseworker — agency staff who use the same or an adjacent system all day. A moved button costs a resident a minute; it costs a caseworker who processes two hundred applications a day a measurable backlog. They need advance notice and specifics, the way instructors do in education software.
  • The intermediary is the reader unique to civic tech: librarians, legal-aid clinics, benefits navigators, accountants, advice bureaus. They help other people use your service, they teach from screenshots, and they are the most efficient distribution channel you have — one well-informed navigator reaches hundreds of residents.
  • The integrating agency consumes your APIs and data feeds. Cross-agency integrations are often maintained by contractors on annual cycles, so a breaking change needs the longest notice window of any audience — everything in the API changelog guide, with the deadlines doubled.
  • The record-keeper — journalists, auditors, researchers, and tribunal panels — reads your changelog as evidence of what the service did and when. You don’t write for them daily, but their existence sets the standard: dated, permanent, never silently edited.

Plain language is a legal requirement, not a style choice

In much of the public sector, plain writing is codified: the U.S. Plain Writing Act, the GOV.UK style guide, and their equivalents elsewhere make clarity an obligation rather than a preference. Release notes inherit that obligation, and it is worth embracing rather than merely complying with, because the plain version is also the useful version.

  • Name screens the way the letter names them. Residents arrive from a paper notice or an email that says “go to Manage my claim.” If your note says the “claimant dashboard module” changed, you have described a system they have never heard of. Use the words printed on the screen and in the letters.
  • Lead with the action, not the change. “You can now upload documents instead of mailing them” beats “Added document upload functionality.” The reader’s question is always “what does this mean I do?”
  • Keep the reading level down and the sentences short. Your service is used by people in a hurry, in a second language, on a phone, in a library time slot. The tone guide’s rules apply with the volume turned up: no idioms, no internal project names, no humor about a process that decides someone’s benefits.
  • Say when nothing is required. In a government context, change reads as threat — a changed form makes people worry their application is now wrong. “You do not need to do anything. Applications already submitted are not affected” is the single most calming sentence you can write, and it belongs in almost every entry.

Did the policy change, or did the service?

The defining confusion of government release notes is that two different things change and readers cannot tell them apart. Sometimes the rules change — a new statute, a revised regulation, an updated fee schedule — and the screens merely follow. Sometimes only the service changes — a redesigned form collecting the same information under the same rules. Residents experience both as “the website is different,” and if your note doesn’t separate them, they will draw the wrong conclusion in both directions: assuming a cosmetic redesign changed their eligibility, or assuming a genuine rule change is just a new coat of paint.

So separate them explicitly, every time. A workable pattern is a two-line opening: what changed in the rules (with the statute or regulation named and linked), then what changed on the screens. If only one of the two changed, say so: “The eligibility rules have not changed. The questions are the same; they are now split across three shorter pages.” The policy-change guide covers the rules side in depth; the discipline here is refusing to let the two blur.

Naming the statute matters for a second reason: it is the honest answer to “why?” But name it as context, not as cover. “Due to recent legislation, some features have changed” is the government equivalent of “bug fixes and improvements” — it cites authority while withholding every fact the reader needs. The legislation set the requirement; you still own telling people exactly what is different and what to do about it.

The civic calendar

Commercial products ship on their own schedule. Public services live inside a calendar set by law: filing deadlines, enrollment windows, certification periods, term starts, elections. That calendar should bend your release schedule, and your changelog should show that it does.

  • Freeze around peak obligation windows. The week before the filing deadline is the worst possible moment to change the filing service — maximum users, maximum stress, zero slack for relearning. Publish the freeze as policy in the changelog (“no changes to the filing flow between April 1 and April 20”) so intermediaries can rely on it while preparing help sessions.
  • Announce ahead with dates, not adjectives. “From 5 January 2027, the renewal form will ask for your document number up front” lets a navigator update their training materials before the change lands. “Coming soon: an improved renewal experience” helps no one and alarms some.
  • Distinguish effective dates from release dates. As in fintech, the date the software shipped and the date the rule takes effect are different facts. A fee change may be live in the code weeks before the statute makes it real. State both.
  • Mid-window changes get the loudest treatment. If you must change a form while an application window is open, the entry must answer the applicant’s only question: does this affect applications already started or submitted? Answer it in the first line.

Your changelog is a public record

Here is the reader most changelogs never plan for: the tribunal. In benefits appeals, immigration hearings, and audit findings, the question “what did the form ask on the day this person applied?” is asked with real stakes attached. A dated, permanent, honestly-kept changelog is one of the few artifacts that can answer it. That possibility should discipline everything about how you keep the log.

  • Never silently edit an entry. If a published note was wrong, publish a correction as a new entry that links the old one, and mark the old one corrected. An edit-in-place changelog is worthless as a record — and public-records and freedom-of-information regimes may treat your published notes as disclosable documents regardless of how you treated them.
  • Date everything, unambiguously. ISO dates, timezone explicit where time matters. “Spring update” is not a date a hearing can use.
  • Keep permalinks stable forever. Advice organizations cite your entries in their guidance; a moved URL breaks the citation chain. The archive guide covers keeping old entries alive; in government the retention answer is simple: all of it, indefinitely.
  • Screenshots in entries earn their keep twice. A picture of the new form is plain-language gold for residents now (screenshot guide) and evidence of what the service looked like later.

Accessibility and language access are announcements

Public services carry accessibility obligations — WCAG conformance, Section 508, EN 301 549, and the accessibility statements those regimes require. Two consequences for the changelog. First, accessibility fixes are real entries, not invisible maintenance: the resident using a screen reader who couldn’t complete the form deserves to know it now works, and your accessibility statement’s “last reviewed” line should link the entries that changed it. Second, if the service is legally available in multiple languages, the notes about the service are part of the service — an English-only announcement of a change to a form you publish in six languages fails the same obligation the form itself meets. The localization guide covers the mechanics; the public-sector rule is just that notes inherit the service’s language commitments.

One more inherited duty: when the change is a security fix in a system holding citizen data, the two-document pattern applies with extra care — precise about impact, vague about mechanism, and never silent, because silence discovered later costs an institution what it can least afford: the presumption of good faith.

A template that respects the reader

A shape that covers the audiences above without jargon:

The renewal form now asks for your document number first — 5 Jan 2027

What changed: The “Renew my license” form asks for your
document number on the first page, instead of at the end. The
questions are otherwise the same.

Why: A rule change (Regulation 2026/14) requires us to check the
number before an application starts. The rules about who can renew
have not changed.

Who is affected: Everyone renewing online from 5 January 2027.
Applications started before that date are not affected.

What you need to do: Nothing in advance. Have your current license
with you when you start.

For organizations that help people renew: an updated step-by-step
guide with new screenshots is at <link>. Printed guides dated
before January 2027 show the old question order.

Help: If you have trouble with the new form, call <number> or
visit any service center.

Note what the template refuses to do: no module names, no statute text pasted in place of an explanation, no enthusiasm. The register is a well-written letter, because that is the register residents already trust the institution to use.

Anti-patterns

  • Legalese as release notes. Pasting the regulatory citation and calling it an announcement. The statute is the why; the note’s job is the what-and-do.
  • The press release instead of the changelog. A minister-quoted announcement on launch day, then nothing, ever again. A press release is one entry’s worth of attention; a service changes weekly. Dated, boring, cumulative notes outlive every press cycle.
  • The silent mid-window form change. Changing questions while an application window is open, announced nowhere. Every applicant who started under the old form now doubts their submission — and support inherits the doubt as calls.
  • “Due to recent legislation.” Authority cited, information withheld. Name the change, name the rule, own the explanation.
  • English-only notes for a multilingual service. The form meets its language obligation; the announcement about the form quietly doesn’t. Notes are part of the service.
  • The cross-agency API break announced in a meeting. A schema change communicated in a quarterly interagency call, minuted nowhere public. The consuming agency’s contractor rotates; the knowledge evaporates; the integration breaks at the worst deadline. Breaking changes get written, dated, permanent notice.

Running it on Wakelog

Wakelog fits civic-tech constraints unusually well, starting with the unglamorous one: it is free, and public-sector and nonprofit digital teams rarely have a procurement path for a changelog tool. Beyond budget: per-entry permalinks give advice organizations and auditors stable citations; scheduled publishing lets you write the entry when the rule is finalized and publish the day the notice period starts; tags separate resident-facing announcements from the technical stream your integrating agencies filter for; and RSS gives journalists and navigator networks a subscription that isn’t a press list. The honest boundary: Wakelog is not an official public-records system, and a changelog entry is not statutory notice where the law requires direct communication — it is the permanent, linkable record that your required letters, emails, and site banners all point to.

Start your changelog — free   Next: announcing policy changes →

Related guides

Last updated 2026-08-01 · All guides