Authoring Release Docs

Produces release notes, changelogs, and READMEs — time-sensitive, high-visibility documentation that users and developers rely on to understand what changed and how to respond.

Prerequisite: Load authoring-technical-docs first for the multi-pass workflow, style rules, and quality framework. This skill provides release-specific templates and rules only.

Templates

Follow the asset at ./assets/release_notes_template.md for release notes structure. For changelogs, follow Keep a Changelog conventions unless a project-specific format is already established.

Core rules

Framing

• Lead with user impact, not implementation detail. Write "You can now export dashboards as PDF" — not "Added PDF rendering pipeline."

• Use past tense for all changes: "Added", "Fixed", "Removed", "Deprecated."

• Write for two audiences simultaneously: technical users who need precision, and non-technical stakeholders who need plain-language summaries.

Structure

• Open with a one-paragraph summary of the most significant changes in this release.

• Group changes by type in this order: Breaking Changes → New Features → Improvements → Bug Fixes → Deprecations.

• Within each section, order by impact: most significant change first.

Breaking changes

• Breaking changes must appear in a prominent callout block — they cannot be buried or easy to miss.

• Always include exact migration steps inline, not just a link to external docs.

• Every deprecation must include a target removal date.

Bug fixes

• Be specific. Write "Fixed an issue where CSV exports truncated rows with more than 50 columns" — not "Fixed export bug."

• Include severity where relevant (e.g., data loss, crash, cosmetic).

Traceability

• Every bug fix and feature entry must reference its issue tracker ID (e.g., Jira ticket, GitHub issue).

• Every release must include a release date.

READMEs

• Must work standalone: a developer finding the repo for the first time should be able to install and run the project using only the README, without consulting any other document.

• The quick-start section must be completable in under 30 seconds.

• Include: project description, prerequisites, installation, quick start, configuration, links to further docs.

Generating release docs from raw inputs

When given Jira exports, commit logs, ticket lists, or PR summaries:

• Triage inputs — identify the type of each item: feature, improvement, bug fix, breaking change, deprecation, or internal/non-user-facing (exclude the last category).

• Rewrite for users — commit messages and ticket titles are written for developers; release notes are written for users. Translate accordingly.

• Group and prioritize — apply the section order above; sort by impact within sections.

• Resolve ambiguity conservatively — if a ticket is too vague to describe accurately, flag it for human review rather than guessing. Do not fabricate specifics.

• Verify completeness — cross-check that every input item is either included or explicitly excluded (with a reason), so nothing is silently dropped.

Output locations

Document Path

Release notes docs/releases/v[version].md

Changelog CHANGELOG.md (project root)

README README.md (project root)