207. What's new: release notes people read

A release can contain a new drawing tool, a larger icon and a fix for the file that would not open. Their entries may occupy similar space in the change log. To the person with that file, they are not similar news.

A useful release page helps readers find the change that affects their work. It explains what differs, preserves the conditions, and makes any required action clear. It also leaves a reliable account for someone comparing versions long after “new” has ceased to be a useful description.

The register guide governs the factual account. An introduction may have warmth and a sense of occasion; behavior, compatibility, migration and known issues keep their precise scope.

Identify the release before describing its merits

State the product, version, applicable platforms and release date where relevant. Make beta, preview, stable and planned status explicit. A reader arriving through search should not need a previous page to discover which release the note means.

Different readers bring different questions. An existing user may want a fix, a migration requirement or a reason to upgrade. A prospective buyer may be checking a capability. A reviewer may need conditions for a demonstration. Give those questions useful routes without assuming one reading order.

A README has a different job: it introduces the project and its maintained entry points, setup and documentation. Link it to release history rather than letting a growing list of changes displace the instructions someone needs now.

Give changes a useful hierarchy

Organize a substantial release around work readers recognize: drawing, spacing, variation, export or scripting, for example. A small patch may need only a few clear entries. Let the release determine the structure.

Kind of change	What the entry needs
Substantial capability	Purpose, mechanism, relevant limits and a useful example
Smaller improvement	The specific difference and its effect on the task
Fix	Triggering conditions and corrected behavior
Changed default or compatibility	Who is affected and what changes for them
Removal or deprecation	Status, scope and any established action or timeline

Hierarchy is an aid to finding information, not a judgement that every short entry matters less. Keep adoption risks visible even when they would make a less attractive opening than the new feature.

For cumulative notes, state the versions being compared. Group related entries without merging distinct fixes into a vague claim. If a total number of changes is advertised, define and check the counting method. A list of bullets is an arrangement of prose, not automatically a product metric.

Write the change as a change

Gather the prior behavior, new behavior, affected work and required action when those facts are available. Keep the issue, test or product record with the editorial notes. The published entry should contain the part readers need.

A heading names the feature or task. The body explains the difference. Now, added, changed and removed are useful words when they describe the actual event; no single construction needs to introduce every entry.

For this fictional release packet:

• Version 2.4 makes millimeters the default unit for new documents.
• Existing documents retain their stored unit.
• No user action is required.

A useful note is:

New-document units. New documents in 2.4 default to millimeters. Existing documents keep their stored unit; no action is required.

The second sentence anticipates a reasonable concern about existing work. That is a form of warmth grounded in information. It does not require “Don't worry,” and it cannot be added when the source has not established preservation.

Avoid a vague “improved” when a concrete difference is known. Do not fill a gap in the old behavior merely to produce a tidy before-and-after account. Sometimes the supported entry can report only the current capability.

Develop a larger change without inflating it

A substantial feature may need a paragraph that moves from a recognizable task to the mechanism and its boundary. Choose a detail that makes the change understandable: a setting retained, a repeated action removed, or a result that can now be inspected directly.

Let the paragraph develop. A longer sentence can connect the operation to its conditions; a shorter one can make a limitation or consequence unmistakable. Avoid turning every sentence into a miniature headline.

An illustration can show the relevant difference, but it must be identified as illustrative. A real customer scene needs a source. Do not add an imaginary late-night deadline to make a routine improvement feel urgent.

The final sentence should leave the reader with the useful result or remaining choice. A slogan after the explanation usually spends the confidence the facts have just earned.

Describe the failure that was fixed

Name the symptom and the conditions under which it occurred. An unexpected exit, a stalled interface, an export error and damaged output are different events. Do not soften one into another or broaden a bounded fix into a stability guarantee.

Fictional packet: opening an empty project caused the application to exit unexpectedly; version 2.4 fixes that condition. Other crash behavior is not established by the packet.

Opening an empty project no longer causes the application to exit unexpectedly.

That sentence gives an affected reader something recognizable. “Improved stability” asks them to infer it. “The application no longer crashes” promises far more than the source supplies.

Keep the logical relationship between multiple conditions. A fix that applies only with a particular format and option must retain both. Split a dense setup when helpful, but do not shorten it by discarding the condition most readers will not happen to need.

A public issue link can add detail. It should supplement a meaningful description, not replace it with a ticket number. Do not rely on strikethrough or color alone to communicate that an issue was resolved.

Explain the cost of adopting the change

Review defaults, commands, shortcuts, file formats, runtimes and support boundaries. Identify what existing users need to do before or after upgrading. Put that information near the change that creates the work.

Keep status terms distinct:

• Fixed: a specified failure has been corrected.
• Changed: behavior differs; the entry must say how.
• Removed: an option or behavior is unavailable in this release.
• Deprecated: it remains available under a stated discouragement or withdrawal policy; removal may have no announced date.
• Experimental: the release marks the capability as experimental, with its actual constraints explained.

Give a replacement, migration command, deadline or workaround only when established. A runtime update does not supply a package-repair command. A menu reorganization does not establish that every shortcut must be reassigned.

Use “no action required” when it answers a likely concern and the source supports it. It is not a decorative closing for every note.

When the company made a decision that imposes work, we can make responsibility clear. Describe the cost plainly. An apology may be appropriate, but it does not replace the explanation or authorize a promise about restoration.

Give a substantial migration its own route

Keep a short action beside its release entry. Link to a separate procedure when prerequisites, branches, checks or recovery would otherwise obscure the news. The boundary follows the task's complexity rather than a fixed number of steps.

The release note should say who needs the procedure and why. The migration guide then provides verified starting conditions, actions and results, following chapter 205.

For a rename, retain the old name where it explains the route to the new one. A name change alone does not establish file compatibility, licence eligibility or identical behavior. Check those separately when they matter.

State the limits that affect adoption

Known issues belong where a reader can use them to decide. Keep the affected version, platform, condition and supported workaround together. If no workaround is known, report that state instead of improvising one.

Separate technical behavior from support policy. A configuration may work in a particular test without being supported. An unsupported configuration is not therefore proven unable to run. The release note needs the applicable claim.

Avoid a broad assurance such as “safe to upgrade” unless its intended meaning and evidence are actually established. Describe compatibility, migration and known limitations so the reader can assess their own work.

Match the evidence to the claim

A screenshot can show a visible change. A demonstration can show an interaction. A performance comparison needs measured results and the conditions under which they were obtained.

Identify the version, platform, sample, settings or hardware needed to interpret the evidence. One successful prepared example remains one example. Do not turn its elapsed time into an unconditional promise about every document.

Captions should tell readers what to notice. Keep consequential conditions in text and provide accessible descriptions for essential visual information; see accessible content.

An announcement can select and arrange release facts for its audience while preserving the same scope, uncertainty and limits. It may lead with the product and change, a relevant observation or a brief scene. A scene is optional. Chapter 306 develops that choice.

Leave a reliable historical account

A release note describes its stated release. Correct errors and repair broken routes, but do not silently replace the old behavior with the current behavior. Add a dated or versioned update when a later release changes the relevant fact.

Use explicit versions and stable anchors. “Recently” becomes a small mystery once the page has been copied, cached or read a year later. The version number continues to do its job.

Preserve historical labels when they identify the interface of that release. Explain later names where necessary for navigation. Keep current setup commands in maintained documentation, with the relationship to older instructions clear.

A cumulative overview may summarize several releases. It should retain links to the detailed accounts and keep distinct conditions intact. Removing repetition is useful; removing the historical difference is not.

Practice: change the surface without changing the event

Use this fictional packet:

• Version 2.4 keeps the last folder used for PDF export within the current session.
• The earlier version reopened that dialog at the project folder.
• Persistence after restarting is not established.
• No time saving has been measured.

Write a reference-style release entry:

PDF export folder. During the current session, the PDF export dialog now returns to the folder used for the previous PDF export. In the previous version, it opened at the project folder.

Then write a short announcement paragraph. Begin with the repeated folder choice, develop the new behavior and retain the session boundary. You may make the situation recognizable; you may not add a saved-click count, a restart promise or a customer's reaction.

An announcement version could read:

In 2.4, the folder chosen for one PDF export becomes the starting point for the next export in that session. The previous choice gets another use.

The second sentence adds a quiet observation rather than another capability. The first carries the complete session boundary; the observation can be removed without changing the fact.

For the second pass, remove the earlier-version fact. Rewrite the entry without manufacturing a comparison. Then change the persistence condition to “only while the project remains open” and revise both versions. A warmer paragraph must carry the same narrower scope as the factual note.

Checklist

• Product, version, status and platform scope are identifiable on arrival.
• Hierarchy helps readers find their change without hiding upgrade risks.
• Entries describe specific differences and preserve every necessary condition.
• Failure types, changed behavior, removals and deprecations remain distinct.
• Required actions and migration routes are supported and usable.
• Known issues and support boundaries retain their actual scope.
• Demonstrations and measurements support the claims made from them.
• Announcement prose develops interest without adding an event or outcome.
• Links and stable anchors preserve useful historical routes.
• Corrections leave the release's historical meaning intact.