[bruno-andrade-azion]

What & why

Related issue: MM-16264
Pages affected: 25 style guide pages under apps/docs/src/content/docs/en/pages/style-guide/ and 25 under apps/docs/src/content/docs/pt-br/pages/guia-de-estilo/. No permalink, frontmatter, or navigation change.

The style guide contradicted itself, and in places the code, on four rules: the hub table, the closing section, the sentence caps, and where a date may appear. This PR settles each rule once, points the other pages at it, and brings every sentence of the guide under 30 words in both languages.

Hub table. Already consistent on main since #2600: the guide, its pt twins, and ProductGuidesSection agree on name, type, and last updated, sorted alphabetically by navigation label (src/nav/resolve.ts:934). The one gap left was the video rows: the table also lists the YouTube videos that src/nav/videos.json tags with the section, with an empty date. Components now says so.

Closing sections. 352 en pages end with ## Related resources, but the guide's own 13 content-type pages ended with ## Related (pt: ## Relacionados). They now use the canonical name. No link pointed at the old anchors. Choose a content type now names the use case's closing, ## Guides in this use case, which the use-case template and all 27 en and 27 pt use-case pages already use. Bilingual pages lists its fixed pt form, ## Guias deste caso de uso.

Sentence caps. The use-case page set Descriptive, 20 words. Sentence structure gave Descriptive 25. Choose a content type made a use case a How-to, which is Procedural, 20. The use-case page itself calls a use case "theory, not a procedure": it explains a design, and every step lives in the guides it links. A use case now takes the explanation base form, with the descriptive 25-word cap. The cap table in Sentence structure lists every page kind with its base form, mode, and cap, including the use case, the changelog, and the navigation hub. Choose a content type, the use-case register, and the multi-resource comparison say the same in both languages. The comparison paragraph also said a use case "configures it, and proves it works"; it now describes what a use-case page holds. Three more sentences said the page builds its design: the absent-kinds list in Choose a content type, the placement list in Information architecture, and the When to use list in Architecture pages. They now say it explains the design and links the guides that build it. The docs-writer skill still applies How-to and 20 words to a use case (references/simplified-technical-english.md), so it needs the same change; it lives outside this repository.

Long sentences. Every sentence over 30 words is split: 47 en sentences and their pt twins, plus 17 pt sentences whose en twin was already 30 words or fewer. The split keeps the meaning, including whether a list is complete or a set of examples. Two run-on lists in Information architecture became bullet lists: the nested Platform Resources by parent, and where a nested resource is documented. The count comes from a script that skips frontmatter, code fences, tables, and JSX lines, counts inline code as one word, and treats a bold lead-in as its own sentence.

Sentences	main en	main pt-br	This PR en	This PR pt-br
Over 30 words	47	63	0	0
Over 25 words	104	161	58	114

Date rule. Five places disagreed. Numbers and units and Changelog said dates appear only in changelogs. Word choice exempted generated dates. Navigation hubs called the hub "the one place" a date may appear outside a changelog, while every page header renders a generated Last updated date (src/components/PageContent/PageContent.astro:42). Terminology allows dated agreements, and Components keeps the API v3 shutdown date in versionDeprecated. Numbers and units now holds the one list of where a date belongs, and Word choice, Changelog, and Navigation hubs point to it. The guide's own prose also loses its two dates: the ASD-STE100 issue date in Sentence structure, which used the day-first order the guide bans, and the example year in Terminology.

Changelog tags. The Changelog page listed tags as optional. pnpm lint:changelog (#2634) and CONTRIBUTING.md require exactly one tag on a new entry, from a closed list. The page now requires one tag, points to that list, and says a new tag joins the list and the check in the same pull request. A second entry on the same date keys its anchor on the tag, as CONTRIBUTING.md says. The archive example also loses its years ("from 2016 to 2021"): it now says the archive holds the entries from before the current release notes, which start in January 2022. Word choice now limits its no-date sentence to hand-written prose, so it no longer contradicts the list of exceptions in Numbers and units.

Merged with main. #2636 (group hubs) changed the same paragraphs of Information architecture and Navigation hubs. The merge keeps its facts inside the split sentences: a group hub for a nested Platform Resource with no Overview, a Quickstart group with a group hub, Shape 3, and the group-hub bullets. The "one place the guide allows a date" sentence that #2636 kept takes this PR's wording. main had also added sentences over 30 words to Reference, Code, and Headings (en and pt-br), which are split here. The Long sentences table was measured before the merge. After the split, a word count over the merged guide finds no sentence over 30 words that this branch did not already pass before the merge.

DocUpdate anchor. Components said label is the anchor. The id does fall back to the slugified label, but the right rail lists only entries that pass anchor (src/util/docUpdateHeadings.ts:20), which is why Changelog requires it. The example now passes anchor, and the bullet says to always pass it.

How I checked it:

• docs_gate.py --check on the 47 files: no new finding. The 3 pt description length findings exist on main.
• rewrite-check.py on each file against main: 0 measured values and 0 link targets dropped in all 47.
• linkcheck.py: 0 broken links, 0 cross-language links, every namespace paired. The URL taught inside code at docs-as-code.mdx:60 (en and pt) fails the same way on main.
• The 8 new or renamed fragments resolve in the built HTML, for example #format-a-date-only-where-a-date-belongs and #recursos-relacionados.
• Greps: no ## Related or ## Relacionados closing left, every register line matches the cap table, no page says dates belong only in changelogs, and no month or year is left in guide prose outside code.
• pnpm build:local after the rebase on main: 2092 pages built, frontmatter check clean.
• After merging main (63993ebc7) and the changelog-tags commit: docs_gate.py --check on the 50 files finds only the 3 pt description lengths that exist on main; linkcheck.py finds 0 broken links and every namespace paired; pnpm build:local built 2156 pages with the frontmatter check clean, and the new Changelog text and the #format-a-date-only-where-a-date-belongs fragment render. The Greps above hold on the merged tree. rewrite-check.py was not re-run on these commits: they drop one fact by design (the archive's years) and turn the tag from optional to required.
• The use-case commits (e9d505a0a and 55ca95fa5, 12 of the 47 files): docs_gate.py --check and linkcheck.py find nothing new; rewrite-check.py against 41ffd0b79 drops 0 measured values and 0 link targets; no prose sentence runs over 30 words; each en and pt pair keeps the same ##, ###, and table-row counts. pnpm build:local on 55ca95fa5: 2092 pages built, frontmatter check clean, and the new text renders on the six en pages and their pt twins.
• Not run: pnpm lint:links, which skips the style-guide tree by design (scripts/lint-links.ts:127). I did not open the pages in a browser.

Left out, for follow-up: scripts/lint-links.ts accepts only ## Next steps and ## Related resources as a closing, so it reports every use-case page. That is a code change and goes in its own PR, #2632. The pt-br Code page lacks the JSON Lines paragraph and the jsonl example that #2642 added to the English page; that is a translation follow-up to #2642.

Type of change

• 🆕 New content (feat)
• 🩹 Fix (fix) — typo, broken link, wrong information
• ♻️ Content update (docs) — rewrite, expansion, upkeep
• 🌐 Translation sync (i18n)
• 🏗️ Platform / structure (refactor / chore) — reviewed by UXE, no content mixed in

Author checklist

• PR title follows type(scope): summary (see GOVERNANCE.md §4)
• Frontmatter complete: title, description, meta_tags, namespace, permalink, last_reviewed — no frontmatter changed; none of the 47 style guide pages carries last_reviewed, before or after this PR
• No legacy "edge-" product names in the copy
• How-to/tutorial content includes at least one runnable, copy-paste-tested code block — no how-to or tutorial page in this PR
• Screenshots (if any) have alt text and follow image standards — no screenshot is added or changed
• Internal links are relative and resolve locally
• If any permalink changed or page moved: redirect added in this PR — no permalink changed and no page moved
• i18n: pt-br updated in this PR or follow-up i18n issue created: pt-br updated in this PR
• I ran pnpm build:local (build + frontmatter check) without errors

[marcus-souza-azion]

Bruno, uma pendência que veio da revisão da #2634 (lint de changelog, MM-16259):

A página de changelog do style guide, em en e pt-br, ainda diz que tags é opcional ("The Platform Resource and the version: tags={['<Platform Resource>']} … when the release names a Platform Resource"). O lint da #2634 exige exatamente uma tag, da lista fechada em .github/CONTRIBUTING.md#changelog-entries. A decisão foi manter o lint como está e alinhar o style guide.

Você consegue incluir nesta PR (MM-16264), nas duas línguas:

• tags passa para os componentes obrigatórios: uma tag por entrada, da lista fechada do CONTRIBUTING;
• description="Version <x.y.z>" / description="Versão <x.y.z>" continua opcional;
• se fizer sentido, uma linha apontando para o pnpm lint:changelog.

A #2634 pode entrar antes desta, e a divergência fecha quando esta entrar.