Generate Release Notes and FAQs from the Ship List

Workflow area: Specs & Docs · Tier: Foundation · Hands-on time: ~20 minutes

The raw material is unambiguous: a list of merged PRs and closed tickets. The transformation is pure writing: engineer-speak into user value, per audience. That's ideal AI territory. The two failure modes are just as specific: the model inflating "groundwork for bulk actions" into "bulk actions are here," and it describing the feature that got reverted on Thursday. Both are caught the same way — checking claims against what actually shipped, not what was planned to ship.

When to use — and when not to

• Use it every releaseweekly ship emails, in-app changelogs, app-store notes, and the customer-facing FAQ refresh; the per-audience rewrite is where the time savings compound.
• Use it to close the docs gapthe same ship list, run against your FAQ, tells you which help articles just went stale.
• Use it when engineering writes the first linea PR title like "fix: debounce approval webhook retries" contains the fact; AI translates, you verify.
• Skip it for incident communicationapologies, outage postmortems, and security disclosures carry legal and trust weight; those are hand-written, reviewed sentences.
• Skip it for the marquee launchthe launch announcement for your biggest feature of the year is positioning work (pb-15's comms pack territory), not changelog translation.

The recipe

1. 1.

   Pull the real ship list, not the plan. Export merged PRs / closed tickets for the release window — titles, one-line descriptions, labels. Explicitly remove anything reverted, feature-flagged off, or dark-launched. This pre-filter is the single highest-value minute in the playbook: the model cannot know what got rolled back; only the list you feed it can.

2. 2.

   Run the translation prompt, per audience.

   Copy

   Turn this ship list into release notes for three audiences.
   
   Product context: [ONE LINE]
   Release: [VERSION / DATE]
   
   Audiences:
   1. CUSTOMER CHANGELOG — value language, no internal jargon,
      grouped as New / Improved / Fixed. One line each.
   2. INTERNAL (sales & support) — what changed, who it affects,
      what to say if a customer asks, links to docs.
   3. APP-STORE NOTES — under 500 characters, plain language.
   
   Rules:
   - Use ONLY the items in the list. Do not infer unshipped
     capabilities from partial work — "part 1 of bulk actions" is
     NOT "bulk actions."
   - Skip internal-only changes (refactors, CI, telemetry) in
     customer-facing outputs; keep them in the internal notes.
   - Mark any item you couldn't confidently translate with [UNCLEAR]
     instead of guessing what it does.
   
   Ship list:
   [PASTE PR/TICKET LIST]
   

3. 3.

   Verify every customer-facing claim against reality. Good output looks like:

   Copy

   NEW
   - Approve up to 50 expense requests at once from the queue view.
   IMPROVED
   - Reminder emails now respect each approver's timezone.
   FIXED
   - CSV exports no longer drop rows when filters are applied.
   [UNCLEAR] "feat: shadow-write approvals to v2 store" — customer
   visible? (Flagged, not included.)
   

   For each New/Improved line, open the feature in staging or prod and confirm it does what the note says, at the limits the note states (is it actually 50?). Numbers, limits, and platform availability are where translation quietly invents precision.

4. 4.

   Resolve the [UNCLEAR] items with engineering. Thirty seconds per item in the team channel: "customer-visible or not?" An [UNCLEAR] that ships as a guess is how "we announced a feature that doesn't exist" happens.

5. 5.

   Update the FAQ against the same list. Second prompt, same conversation: "Here are our current FAQ entries [PASTE]. Given the ship list, which answers are now wrong or incomplete? Draft the updated text for each, marking what changed." Review the diffs — stale docs generate support tickets at a rate no release note offsets.

6. 6.

   Read the customer changelog once as a customer, then ship it. Tone check: does it sound like your product, or like every AI changelog ("We're thrilled to announce...")? Cut the thrill, keep the facts, publish through your normal channels.

Make it yours

• Notion AI in your release hub: if ship lists and notes live in Notion, run the translation in-place and keep a per-release page with list, notes, and verification checklist together — the audit trail is a page history.
• Claude Project with voice examples: store three past releases' final (human-edited) notes as exemplars in project instructions — output arrives in your product's voice, and the "thrilled to announce" tax disappears.
• Team scale: wire a release-branch automation (GitHub Action or Zapier) to dump the merged-PR list into a channel on release cut, so the raw material shows up on schedule; the translation and verification stay with the release owner.

Quality check

• Every claim maps to a shipped itemnothing in the notes lacks a PR/ticket in the list, and nothing reverted made it through; check the revert list one final time.
• Capabilities aren't inflatedpartial or flagged work described as done is the signature failure; re-read every "New" line asking "can a customer do this today?"
• Numbers and limits verified in-productthe 50 in "up to 50" was tested, not transcribed.
• Audience separation heldno internal codenames, ticket IDs, or "customers were affected by a bug for 3 weeks" phrasing leaked into the public version.
• The FAQ was actually updatedrelease notes without doc updates just move the confusion to the support queue.