Inline-header lists that restate the heading
The shape is always the same. A dash, a bold word, a colon, a sentence that repeats the bold word. User Experience: the user experience has been improved. Performance: performance has been enhanced. Security: security has been strengthened.
That is not a list of facts. It is a list of category labels with slogans attached. Pattern 16 in REhume converts it to prose. I do the same by hand when I am not running the tool.
A concrete rewrite
Before:
- User Experience: The user experience has been significantly improved with a new interface.
- Performance: Performance has been enhanced through optimized algorithms.
- Security: Security has been strengthened with end-to-end encryption.
After: The update improves the interface, speeds up load times through optimized algorithms, and adds end-to-end encryption.
The after version still has a triad, which I may break later if the release notes only shipped two of those things. Honesty about what shipped matters more than the list shape.
When the labels are data
A YAML-ish list is fine when the left side is a real key: timeout, region, retry_count. Those are field names. Bold marketing nouns are not field names.
I also keep definition lists in glossaries. “HSTS: a header that tells browsers to use HTTPS” is a definition. “Innovation: we innovate to deliver value” is a loop.
How I edit
I look at the words immediately after the colon. If they repeat the label, I delete the label and keep the rest, or I delete the rest and promote the label to a heading with a real paragraph under it.
REhume’s deterministic pass prefers prose. If I needed a table, I make a table with two columns that are actually different: name, and behavior. I do not make a table of synonyms.
Stacking with other style tells
These lists almost always arrive in title case with boldface and sometimes emoji. I strip style first. Then I ask whether I have three facts or three labels.
They also love significance inflation: “Security: security has been strengthened, underscoring our commitment.” Cut the commitment. Keep the encryption.
Practice
Take a generated “what’s new” list. Write one sentence per shipped item with a verb in the past tense: “We added end-to-end encryption.” If you cannot name the verb, the item was not shipped. It was a theme.
I would rather publish three short sentences than a vertical poster that could apply to any release in any year.
The pattern encyclopedia has the skill example. Use this page when the autofix turns a list into a paragraph and you need to check that the paragraph still matches the changelog.