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) |