From 40cd3b3529c017c56e55333137fb3b06a4cb52d0 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Thu, 27 Aug 2026 17:32:37 -0400 Subject: [PATCH] docs: strengthen the shared skill's proportionality rule MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Folds in the text from pipecat-ai/pipecat#5470, which is still open against pipecat's local SKILL.md and would otherwise be lost when that copy is retired in favour of this one. The version here had the substance but not two specifics worth keeping: the test for whether a note earns its place (judge it with the diff covered up — if it only makes sense as an explanation of what changed, it belongs in the changelog), and the worked example of a default moving from True to None, where the note is warranted only if None confuses someone meeting it for the first time. Also takes #5470's sharper wording for the changelog guideline and its checklist item, which names the failure directly rather than restating the principle. --- automation/update-docs/SKILL.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/automation/update-docs/SKILL.md b/automation/update-docs/SKILL.md index 971d574a..fe1a733e 100644 --- a/automation/update-docs/SKILL.md +++ b/automation/update-docs/SKILL.md @@ -135,10 +135,22 @@ For each doc page that needs updates, edit **only the sections that need changes #### Proportionality -Match the size of the doc change to the size of the source change. A one-line -default change is a one-line doc change. Before adding a new section, a callout, -or a paragraph of explanation, check whether the existing page already covers it -in the place a reader would look. +Match the size of the doc change to the size of the source change. A changed +default is a changed default: edit the value and, if it needs one, the clause +beside it. A two-line source change should not produce a paragraph. When a diff +suggests more prose than the change warrants, that prose is usually explaining +the change rather than the API. + +Add a note only when the behavior would surprise **a reader who has never seen +the previous behavior**. Judge it with the diff covered up: if the note only +makes sense as an explanation of what changed, it belongs in the changelog, not +here. + +A behavior change is not by itself a reason to add a note. The question is +whether the _new_ behavior needs explaining on its own terms. A default that +moved from `True` to `None` needs the default updated; it needs a note only if +`None` is confusing to someone meeting it for the first time — and then the note +explains `None`, not the move. Do not add a ``, ``, or `` for a change that fits in the sentence that is already there. Callouts are for behavior a reader would @@ -296,7 +308,7 @@ After all edits are complete, print a summary: ## Guidelines - **Write for a future reader, not the diff** — docs describe the API as it currently stands. Never narrate the change itself: no "newly added," "this replaces," "recently changed," or references to prior behavior. A reader landing on the page should see no sign that a PR just edited it. Match the weight of the prose to the feature — a routine new parameter gets a one-line description, not a paragraph. -- **The changelog is not the doc** — a PR description or changelog entry explains a change to someone who knew the old behavior. A doc page explains current behavior to someone who has never seen either. Take facts from the changelog; never take its framing, its rationale, or its comparisons. +- **Don't carry the changelog's reasoning into the docs** — the PR body and the changelog entry argue for a change to someone who knew the old behavior. The docs describe the current state to someone who doesn't. Those need different prose, so the changelog is a source of _facts_ here — the new default, the new name, what a parameter now does — and never a source of sentences. Copying its justification across is the most common way a small change turns into a paragraph, and it survives the rule above because a justification carries no "newly" or "previously" to strip out. - **Avoid LLM tells** — write plainly. Skip filler and AI-signalling phrases ("delve," "seamless," "leverage," "it is worth noting," "this underscores"), formulaic "not just X, but Y" contrasts, and overuse of em dashes or boldface. Never leave placeholder text (`[X]`, `{placeholder}`) or assistant meta ("I hope this helps") in a page — this skill runs unattended in CI, so nothing downstream will catch it. - **Keep code and prose in sync** — when a page names a parameter, class, or identifier, spell it in prose exactly as the source and the ``/table entry do. After editing a code example or renaming a param, re-read the surrounding prose for stale references. - **Backtick inline technical terms** — wrap parameter names, class names, filenames, env vars, and config keys in backticks when they appear in prose (Overview, Notes, descriptions). Structured elements like `` already format these inside tables. @@ -316,7 +328,7 @@ Before finishing, verify: - [ ] No content was removed unless the corresponding source was removed - [ ] New parameters have accurate types and defaults from source - [ ] Deprecated items are marked as deprecated rather than deleted or left unmarked -- [ ] The size of each doc change is proportional to the source change +- [ ] The edit is no larger than the change: no note or paragraph that only makes sense as an explanation of what changed - [ ] Formatting matches the existing page style - [ ] Guides referencing changed APIs were checked and updated - [ ] New pages were registered everywhere the profile requires