docs: standards index and stale rules - #2903
Open
TC-MO wants to merge 16 commits into
Open
Conversation
Merge six topic files into style-guide.md and page-structure.md, add a README index, and drop the rule digests from AGENTS.md now that Vale enforces them.
Three of the four subagents were re-deriving linter output. Two remain, for judgment no rule expresses.
accepts.txt doesn't exist, and the PR check only gates errors.
Markdownlint already covers both, via MD045 and MD040.
The default level hid sentence case. Promote Microsoft.Headings to warning; the CI error count is unchanged.
Both were unowned, so reporting them was luck.
TC-MO
added
adhoc
Contributor
|
✅ Preview for this PR (commit |
Marcel flagged that the skill rework dropped terminology checking. He was right, though not for the reason given: scope: [summary, heading] doesn't restrict these rules, and both fire in body prose. Probing one violation per rule in the terminology section shows Vale covers only the product-name cluster. Feature and concept terms, generic technical terms, crawler/scraper casing, legacy vs alternative vs deprecated, version numbers in prose, and the products that require "the" all had no owner after subagent 3 was removed. ApifyProductNames catches only the direction where an article must be removed. Subagent 1 now owns that remainder, listed explicitly in process.md.
13 tasks
Subagent 1 keeps only legacy vs deprecated and acronym first use. The other 27 rules move to apify/vale-rules#3. Blocked on that issue: they are unenforced until it ships.
Drops the dead-rule notes, the vale-rules#3 section, and the design rationale. process.md 878 to 564 words, SKILL.md 411 to 341.
Rule names break silently on rename, as in #2870, and Vale prints them at runtime. Also aligns "the page being reviewed" across both files.
szaganek
reviewed
Sep 3, 2026
| Spawn subagents only for what no tool can check. Each reads the page being reviewed plus one standards file, and returns findings with line numbers and suggested fixes. | ||
|
|
||
| Why subagents: each standards file gets dedicated attention. A single-pass review with a summary tends to miss edge cases (comma rules, article usage, brand spelling) that a focused read catches. | ||
| - Subagent 1, `standards/style-guide.md`: bold used for anything other than a UI element or critical warning, link text that isn't genuinely descriptive, parallel structure in lists, Oxford commas, legacy vs alternative vs deprecated used precisely, and acronyms expanded on first use |
Contributor
There was a problem hiding this comment.
Might be tired, but the first examples seem to be mistakes to flag, but then it seems to switch, because we do use an Oxford comma and the acronyms should be explained on first use.
|
|
||
| ## Front matter | ||
|
|
||
| Every documentation file needs YAML front matter: |
Contributor
There was a problem hiding this comment.
That's a super nit, but in tech frontmatter tends to be one word?
Contributor
Author
There was a problem hiding this comment.
I've actually seen both used interchangably sometimes even within one publication :D but don't see an issue and we can swap to frontmatter
|
|
||
| ## Admonitions | ||
|
|
||
| Use Docusaurus admonitions for important information. All admonitions must have titles. |
Contributor
There was a problem hiding this comment.
I'd add a note that the number of admonitions should be limited, and that they shouldn't replace the regular prose. Our docs use them way too often for things that really don't need to be emphasised this much.
Both spellings were in use, with AGENTS.md already on the one-word form in five places. Settles on it repo-wide, matching the existing check-frontmatter.sh script name.
Adds a density ceiling of one per H2 section and a rule that admonitions carry asides rather than content the prose needs, with a checklist item and a reviewer note to match. Per review feedback that the docs box far more than warrants the emphasis.
The style-guide bullet mixed violations to flag with compliant states, so "Oxford commas" and "acronyms expanded on first use" read as things to report. Every item now names the violation. Drops the acronym check, which Microsoft.Acronyms already reports, and extends the page-structure subagent to admonition density.
Resolves two conflicts in standards/: - writing-style.md: deleted here, modified on master by #2904. Keeps the deletion. The no-stacked-headings rule that #2904 added to it is ported to page-structure.md in the next commit. - quality-standards.md: keeps both sides, the "frontmatter" wording from this branch and the no-stacked-headings checklist item from #2904.
Preserves the rule #2904 added to the deleted writing-style.md, now under a Hierarchy / No stacked headings split in page-structure.md. Neither Vale nor markdownlint reports stacked headings, verified, so it also joins the reviewer-only list and the review-docs page-structure subagent.
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
3 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.
Six files in
standards/merged intostyle-guide.mdandpage-structure.mdwith a README index, andAGENTS.md,CONTRIBUTING.mdand review-docs now point there instead of restating rules Vale enforces.An A/B eval of review-docs against master confirmed no loss of coverage.