Allocate the reader's attention
Identify what the reader came to decide, understand, or do. Reader attention is finite. Predict how much attention this piece will receive before choosing its scope and depth. Use supplied preferences; otherwise state a reasonable assumption in private notes. Treat that estimate as an editorial choice, not a measured reading time.
Review the whole document before polishing individual sentences. A document can use plain words and short paragraphs while demanding too much attention.
Decide what earns space
Give space according to consequence for this reader, rather than the number of changes or the author's effort.
- Lead with the facts that affect the reader's decision or next action.
- Explain important changes enough to show their effect, evidence, and limits.
- Give smaller changes a brief mention or a useful reference.
- Put specialist detail beside its use, in a linked guide, or in an optional reference section.
Do not give every feature the same heading, paragraph count, example, or explanation of why it matters. Do not fill a template's available slots with weaker points. Shorten low-value explanations before compressing the important explanation until it becomes cryptic. Avoid turning everything into a dense list of nouns and identifiers.
Preserve critical prerequisites, warnings, and actions on the main reading path. Optional detail must not hide a condition the reader needs before acting. Keep substantive meaning through compression or a checked reference. If removing meaning falls outside the requested scope, propose that removal before editing it away.
Apply to release notes
An initial scan should help the reader decide whether to upgrade and identify any required changes. Give new capabilities and measured improvements enough detail to assess their value. Lead with the measured gains that convey the most useful meaning to this reader. Keep the baseline and essential qualifications beside them. Link to raw results and method for detail. Do not choose a weaker baseline to make a larger percentage or imply speed from size alone. Make support requirements and consequential migration warnings easy to find. Keep smaller fixes concise. Use the changelog and migration guide for complete lookup detail.
Use a different shape for each destination when it serves the reader. A GitHub release can introduce the changes and link to a longer article. Do not duplicate that whole article by default.
Check the reading path
Read only the opening, headings, and first lines. What can the reader decide from that scan? Then read the main path without optional detail. Does it provide enough context to act safely? Check whether repeated explanations add meaning or just require another pass over the same fact. Check that important changes receive more attention than minor fixes.
Record concrete reading problems and repairs outside the published text. Word counts, punctuation checks, and an agent's approval cannot establish that a human reader finds the result useful.