How to Create a Release Notes Page

It is the morning after a major release. The deployment went smoothly, the monitors are green, and the engineering team is already in the next sprint planning meeting. Then the support tickets start rolling in. Customers are asking how to use the new feature. Sales reps are confused about what actually shipped. The product manager is frantically piecing together a summary from a dozen Jira tickets, three Slack threads, and a PR description that reads "misc cleanup."

You realize that shipping the code was only half the job.

If you have been asked to stand up a proper release notes page, you are probably dealing with one of two situations: you have nothing, or you have something that technically exists but nobody reads. The email blasts, the PDF attachments, the Slack announcements pinned to a channel nobody checks. These are not release notes systems. They are release notes avoidance.

A proper release notes page is a public, persistent, structured record of what your product has done and when. Getting there requires a handful of decisions that are worth making deliberately.

Where the notes actually live

The first decision is hosting. You have two main structural options: a subdomain (changelog.yourcompany.com) or a subdirectory (yourcompany.com/changelog).

From an SEO standpoint, subdirectories tend to perform better. They concentrate domain authority on your primary site, so when users search for your product's release history, those pages benefit from the trust your main domain has already built. Subdomains are often treated as separate sites by search engines, which means you are starting their authority from zero. The Cloudflare engineering blog has a thorough breakdown of the tradeoffs, and the general consensus among technical SEO practitioners is that subdirectories win unless you have a strong operational reason to separate the content.

For the technical stack, you have three realistic options:

• Static site generator (SSG): Tools like Docusaurus or Astro let you write notes in Markdown, commit them to a repository, and deploy automatically. Fast, secure, and developer-friendly. The downside is that non-technical contributors need a Git workflow to publish anything.
• Headless CMS: Separates content from presentation. A product manager can log in and publish a note without touching a terminal. The tradeoff is setup complexity and an additional dependency to maintain.
• Database-backed system: Suitable if your release notes need to integrate with other product data, support rich filtering, or feed into multiple surfaces (in-app banners, email digests, API endpoints). More powerful, more to maintain.

Look at how Stripe handles this. Their changelog is embedded directly in their documentation site, versioned by named release (Dahlia, Clover, Basil), and categorized by product area. It is fast, searchable, and deeply connected to the rest of their developer content. The URL structure (docs.stripe.com/changelog) keeps it inside the main domain's authority.

The anatomy of a useful entry

A 2020 empirical study of 32,425 release notes across 1,000 GitHub projects, published in IEEE Transactions on Software Engineering, found that the two most frequently documented categories of information are issues fixed and new features. That tracks with what users actually want. But the same study found significant discrepancies between what release note producers think is important and what users actually need, with producers overweighting non-functional requirements while users prioritize new feature information.

The practical implication: structure your entries to lead with what changed for the user, not what changed in the code.

A well-formed release note entry contains:

• Summary: One or two sentences describing the change in plain language. What is different, and why does it matter?
• Feature descriptions: For new capabilities, explain what the feature does and how to access it. Link to documentation.
• Bug fixes: Brief descriptions of what was broken and what is now fixed. You do not need to explain the root cause.
• Breaking changes: These deserve their own clearly labeled section. If something will break in a user's integration or workflow, say so explicitly, and include migration instructions. The Keep a Changelog project puts it plainly: "If you do nothing else, list deprecations, removals, and any breaking changes."
• Upgrade instructions: For versioned software, tell users what they need to do to get the update.

Linear's changelog is a good model for how to handle the dual-audience problem. Each entry has a narrative section explaining the feature in product terms, followed by a structured list of fixes and improvements. The technical readers can scan the list; the non-technical readers can read the prose. GitHub's changelog takes a different approach, using short tagged entries (Release, Improvement, Retired) that are filterable by category. Both approaches work. The key is consistency.

Figma's release notes archive is worth studying for a third pattern: monthly summaries with visual context. Screenshots and short video clips make the changes tangible for designers who process information visually.

The part everyone gets wrong

Most release notes pages start strong. The first few entries are detailed, well-written, and published within a day of the release. Then the enthusiasm fades. The entries get shorter. The gaps between releases and notes grow from days to weeks. Eventually, the page becomes a monument to good intentions.

The writing is usually fine. The governance is the problem.

Research on release note production in practice has found that projects using agile development methods are particularly prone to inconsistent or low-quality release notes. The pace of iteration outstrips the capacity to document it.

The fix is to assign ownership before the first entry is published, not after the process has already broken down. Someone needs to own the release notes page the way a product manager owns a roadmap. That means:

• A defined trigger for when a note is required (every release, every sprint, every user-facing change)
• A clear author (product manager, technical writer, or the engineer who shipped the feature)
• A review step that does not require a committee
• A publication deadline tied to the release, not to someone's availability

The governance model does not need to be elaborate. A simple rule like "the PM writes the entry within 24 hours of deployment, and it goes live after a five-minute review from the lead engineer" is more effective than a detailed process that nobody follows.

The engineering handoff problem

Even with governance in place, the hardest part of maintaining release notes is the information transfer from engineering to whoever writes the notes.

Engineers know what changed. They were there. But by the time the release is out, they are already three context switches deep into the next feature. Asking them to write a user-facing summary at that point is asking them to context-switch back into a mode they have already left.

The Conventional Commits specification addresses part of this problem. It is a lightweight convention for structuring commit messages with prefixes like feat:, fix:, and BREAKING CHANGE:. When commits are structured this way, tools like Semantic Release can automatically determine the next version number and generate a draft changelog from the commit history.

PR templates are the other lever. A PR template that includes a required "User-facing change" field captures the plain-language description of the change while the engineer is still thinking about it. That field becomes the raw material for the release note.

The catch is that neither structured commits nor PR templates produce release notes that are ready to publish. A 2022 study on automated release note generation from pull requests found that while deep learning approaches can generate notes similar to manually written ones, the output still requires human review for accuracy and tone. A more recent 2025 paper, SmartNote, found that LLM-powered generation outperforms prior approaches on completeness and organization, but the researchers still emphasize the importance of contextual awareness and human oversight.

Automation accelerates the first draft. The judgment required to make that draft worth reading still belongs to a person.

The teams that get release notes right treat the engineering workflow as the input and the release notes page as the output, with a lightweight human review step in between. The teams that struggle treat the release notes page as a separate project that someone has to remember to update.

Anyway. The gap between those two approaches is mostly a tooling problem.

Doc Holiday is built to close that gap. It connects directly to your codebase, commits, PRs, and ticketing system, generates structured release note drafts from that context, and surfaces them for review in a dashboard where a writer or PM can edit and publish without ever needing to chase down an engineer for details.