diff --git a/learn/ai-for-docs/ai-write-release-notes-automated-review.md b/learn/ai-for-docs/ai-write-release-notes-automated-review.md new file mode 100644 index 000000000..c32e86bfb --- /dev/null +++ b/learn/ai-for-docs/ai-write-release-notes-automated-review.md @@ -0,0 +1,75 @@ +--- +seo: + title: Use AI to write release notes that pass an automated review + description: Draft release notes with AI against the same checklist your automated reviewer already runs, so entries pass on the first read instead of bouncing back. +--- + +# Use AI to write release notes that pass an automated review + +Most release notes get written twice. A developer closes out a ticket with "Fixed bug in API," a reviewer bounces it back for specifics, and the same line gets rewritten under deadline pressure right before a release ships. That back and forth wastes review cycles that a better first draft could have avoided. + +Doc teams increasingly review "changelog entries" with AI before a human ever opens the pull request, against a short "checklist" that names what a passing entry looks like. Fewer teams flip that same checklist around and hand it to AI at draft time instead of catch time. Here is how to write release notes that already match what your reviewer bot checks for, so fewer entries bounce back at all. + +## Why release notes bounce back from review + +Release notes fail review for a small number of predictable reasons. The summary names a symptom without a cause, so a reader cannot tell whether the fix affects them. The entry mixes tenses, describing a shipped change as something that "will" happen. Or the note skips the detail a support team needs most: which endpoint, which flow, which edge case. + +A less obvious cause is scale. One writer can hold a house style in their head, but a release with contributions from a dozen engineers will not read consistently unless something outside any one person's memory enforces the pattern. That is usually where a bot enters the picture, checking every entry the same way regardless of who wrote it. + +None of these problems are hard to fix once someone names them, which is exactly what a good checklist does. [Use AI to accelerate and improve reviews](https://redocly.com/learn/ai-for-docs/ai-reviews) makes the case that a one-page checklist gets better and more consistent results from an AI reviewer than a long style guide written in full sentences, because each line is a single, checkable claim. The same checklist that catches a vague entry after the fact can just as easily guide the writer before the fact, and that reversal is what this article covers. + +## Draft against the checklist your reviewer already runs + +If a pull request pipeline already scores changelog entries against a style checklist, that checklist should not live only on the review side of the process. Paste it into the same prompt a writer uses to draft the entry, alongside the commit message, the linked ticket, and any relevant lines from the diff. + +This works because AI applies a checklist the same way whether it runs before or after a human sees the text. [Use AI to enforce tone and style consistency across docs](https://redocly.com/learn/ai-for-docs/ai-enforce-tone-style-consistency-across-docs) makes a related point about versioning that checklist in Git next to the docs, so tone policy changes are reviewable like code. Once the checklist is versioned, drafting and reviewing both point at the same file, and the two steps stop disagreeing with each other. + +### A short changelog checklist + +- Names the affected endpoint, flow, or component +- States the symptom a user would notice, not just the internal cause +- Uses present tense for something already shipped +- Spells out any action the reader needs to take +- Skips internal ticket numbers unless a reader can act on them + +## Turn a vague change into a note that passes on the first read + +A short before and after shows what the checklist catches. + +> Before: Fixed pagination bug. +> +> After: Fixed an issue where the `next` cursor repeated the same results page when a filter and a sort parameter were combined, so paginated responses now advance correctly under that combination. + +The first version passes no one's checklist because it names neither the affected parameters nor the symptom a caller would see. The second version gives a reader enough to decide, in one sentence, whether the fix touches their integration. Asking AI to draft toward that second version from the start, rather than editing toward it after a rejection, is the entire savings this approach offers. + +## Ask AI to write to your release note template + +A practical prompt gives AI three inputs: the diff or commit summary, the changelog checklist, and a short template for the note itself, such as what changed, why it matters, and what the reader should do next. Ask for the result in that exact order, and ask the model to flag any checklist item it could not satisfy from the information provided, rather than guessing. + +```markdown +Here is a commit diff and its linked ticket. +Draft a changelog entry using this checklist: +[paste checklist] + +Use this order: what changed, why it matters, what to do next. +If any checklist item lacks enough information in the diff, say so instead of guessing. + +Diff and ticket: +[paste here] +``` + +That last instruction matters more than it looks. A model that guesses at a missing detail produces a note that reads well but fails review for accuracy instead of vagueness, which is a harder problem to catch than the original blank was. + +Feed the same prompt the checklist file path rather than a pasted copy when the checklist lives in the repository, so a change to the checklist reaches every future draft without anyone updating a prompt template by hand. That small habit is what keeps the draft-time checklist and the review-time checklist from quietly drifting apart after a few months of edits. + +## Where automated review and human judgment still decide + +Drafting against a checklist shrinks the review loop. It does not remove the review itself, and it should not try to. [Use AI to automate documentation reviews in your PR workflow](https://redocly.com/learn/ai-for-docs/ai-automate-documentation-reviews-pr-workflow) describes a three-layer model that still applies here: an AI checklist lane on the written entry, a [Redocly CLI](https://redocly.com/docs/cli) lint lane on anything the spec can verify deterministically, such as through the [lint command](https://redocly.com/docs/cli/commands/lint), and a human lane for judgment calls a checklist cannot encode. + +A release note can satisfy every line on a style checklist and still be wrong about what shipped, so a human still needs to confirm the entry against the shipped change before merge. That confirmation is where teams often [review a pull request in Reunite](https://redocly.com/docs/realm/reunite/project/pull-request/review-pull-request), reading the note beside the diff it describes rather than in isolation. Wiring lint into the same pull request, as the [Redocly and GitHub Actions](https://redocly.com/blog/consistent-apis-redocly-github-actions) post walks through, keeps the deterministic checks running on the same commit the AI draft and the human review both see. + +[How AI fits into modern API documentation](https://redocly.com/learn/ai-for-docs/ai-modern-api-docs) frames this split simply: AI writes, and the deterministic tooling around it verifies. Draft-time AI narrows the distance between a first attempt and a passing entry, but the checklist, the lint rule, and the reviewer each still do a job the others cannot. + +## How Redocly can help + +Once a changelog checklist exists, [Reunite](https://redocly.com/reunite) is where the release note, the diff it describes, and a reviewer's sign-off meet in one Git-based pull request, so approvers see the rendered change alongside the text rather than guessing from raw Markdown. Pair that review step with [Redocly CLI](https://redocly.com/docs/cli) lint on the same pull request to catch anything the checklist cannot, such as a spec change the note failed to mention, so drafting with AI, reviewing with AI, and verifying with deterministic rules all point at the same commit before it merges. diff --git a/learn/ai-for-docs/sidebars.yaml b/learn/ai-for-docs/sidebars.yaml index 7dd3c8899..86cccabcc 100644 --- a/learn/ai-for-docs/sidebars.yaml +++ b/learn/ai-for-docs/sidebars.yaml @@ -16,6 +16,8 @@ label: Use AI to review code examples for completeness and accuracy - page: ai-automate-documentation-reviews-pr-workflow.md label: Use AI to automate documentation reviews in your PR workflow +- page: ai-write-release-notes-automated-review.md + label: Use AI to write release notes that pass an automated review - page: ai-review-docs-navigation-structure.md label: Use AI to review your docs navigation structure - page: ai-enforce-api-style-guide-at-scale.md