docs: remove intro sentences that restate the page description - #382
Merged
Conversation
The docs layout already renders the frontmatter description beneath the page title, so intros that repeated it displayed the same line twice. Across 53 pages, removed or rewrote those opening restatements so the body now opens with new detail. Machine translation rendered the duplicate copies inconsistently, which this also resolves.
Fixes a dangling pronoun, sweeps three more pages that broke the new rule, tightens the DOCS-SKILL intro wording, and adjusts openers for consistency across sibling reference pages.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The docs layout renders each page's frontmatter
descriptiondirectly under the title. 56 pages also opened the body by restating that sentence, so readers saw it twice in a row. Machine-translated locales make it worse: the two copies translate independently and render as two different sentences saying the same thing back to back (reported on/it/docs/python/reference/functions/declare-var).What this changes:
DOCS-SKILL.md(Page structure item 2, plus a consistency-check bullet), in the same spirit as fix(docs): remove duplicate page titles #378's duplicate-title rule, so newly authored pages stop reproducing the pattern.Root cause: the skill required reference descriptions to summarize the page, required the intro to state what the page is, and never said the layout already renders the description. Pages authored to the guide during the refactor wrote the same sentence twice.
How it was verified:
validate:unsafe-html(414 files),validate-links(368 files), the scripts tests, and a fullpnpm build:content(430/430 pages) pass on this branch.declare_var,useLocales,formatList,gt init) show title, description once, then the new intro. The echo is gone.Notes:
DOCS-SKILL.md; whichever lands second needs a trivial rebase. My edits there are two additive sentences.