Unverified Commit 3da18032 authored by Joseph's avatar Joseph Committed by GitHub

docs: vocabulary-bridge rule for api-ref and guide skills (#94127)

Update skills to consider bridging new terminology to keywords used in
Pages Router, or other parts of URL/HTML spec, etc.
parent c1c33c92
...@@ -120,6 +120,13 @@ description: {API Reference for the {API name} {function|component|file conventi ...@@ -120,6 +120,13 @@ description: {API Reference for the {API name} {function|component|file conventi
| "You can conveniently access..." | "Returns an object containing..." | | "You can conveniently access..." | "Returns an object containing..." |
| "The best way to handle navigation" | "`<Link>` extends the HTML `<a>` element to provide prefetching and client-side navigation" | | "The best way to handle navigation" | "`<Link>` extends the HTML `<a>` element to provide prefetching and client-side navigation" |
13. **Bridge new framework terms with legacy or generic vocabulary.** When the API renames or differentiates from a prior concept (Pages-era term, generic web term, REST vocabulary), include one such synonym in the frontmatter `description` and once in prose. Example: `description: "Use Dynamic Segments to read URL parameters and generate routes from dynamic data."` mentions "URL parameters" alongside "Dynamic Segments". One synonym, folded into natural prose. No separate "Synonyms" or "Also known as" section, no keyword stuffing. Goal: preserve discoverability for users still searching the old vocabulary even when the framework has moved on.
| Don't | Do |
| ---------------------------------- | ------------------------------------------------------------------------------------ |
| "Learn how to use Route Handlers" | "Build API endpoints with Route Handlers, the App Router replacement for API Routes" |
| "Configure dynamic route segments" | "Read URL parameters from dynamic route segments" |
## Workflow ## Workflow
1. **Ask for reference material.** Ask the user if they have any RFCs, PRs, design docs, or other context that should inform the doc. 1. **Ask for reference material.** Ask the user if they have any RFCs, PRs, design docs, or other context that should inform the doc.
......
...@@ -110,6 +110,13 @@ Next, learn how to: ...@@ -110,6 +110,13 @@ Next, learn how to:
| "requires dynamic processing" | "output can't be known ahead of time" | | "requires dynamic processing" | "output can't be known ahead of time" |
| "The component blocks the response — causing delays" | "The component blocks the response. This causes delays." | | "The component blocks the response — causing delays" | "The component blocks the response. This causes delays." |
9. **Bridge new framework terms with legacy or generic vocabulary in `description` and intro.** Guides win or lose SERPs on the colloquial query (e.g. "next js form submission", "next js api endpoint", "next js error page"), not on the framework's preferred noun. When the guide covers a renamed or differentiated concept, include one synonym (Pages-era term, REST/web term, or industry-standard label) in the frontmatter `description` and once in the introduction. Fold into prose. No separate "Synonyms" or "Also known as" section.
| Don't | Do |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| "Learn how to use Route Handlers" | "Build API endpoints (formerly API Routes) with Route Handlers" |
| "Learn how to mutate data with Server Functions" | "Submit forms and update data with Server Functions, the App Router approach to form posts and API mutations" |
## References ## References
Read these guides in `docs/01-app/02-guides/` before writing. They demonstrate the patterns above. Read these guides in `docs/01-app/02-guides/` before writing. They demonstrate the patterns above.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment