Correct and refine the docs-review skill#657
Conversation
Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
Refines the docs-review skill guidance for documentation reviews, with emphasis on end-of-page navigation patterns and ensuring new pages aren’t isolated.
Changes:
- Replaces the “Next steps section” requirement with a broader “page ending pattern” guideline.
- Adds guidance to verify inbound links for newly added documentation pages.
- Extends the review checklist to include inbound-link verification for new pages.
| - **Quickstarts in product sections**: Quickstarts live inside their product section, not in a separate top-level section. | ||
| - **Integration placement**: Third-party integration guides (ngrok, Vault, OpenTelemetry, Okta, etc.) belong in `integrations/`, not in a product section. | ||
| - **Next steps section**: Every how-to guide and tutorial page must end with a "Next steps" section containing 1-3 forward links. Missing "Next steps" is a primary issue. | ||
| - **Page ending pattern**: How-to guides and tutorials follow this closing pattern: Next steps > Related information > Troubleshooting (if applicable). "Next steps" contains 1-3 forward links to the next logical pages. Missing "Next steps" is a primary issue. |
There was a problem hiding this comment.
The "Page ending pattern" bullet asserts a strict section ordering (Next steps > Related information > Troubleshooting), but this doesn’t appear to be a consistently followed convention in the repo and it may conflict with the style guide’s guidance. For example, STYLE-GUIDE.md:169 says pages "end with" a "## Next steps" section, while some existing how-to guides place Troubleshooting before Next steps (e.g., docs/toolhive/guides-ui/playground.mdx:204-267). Consider rewording this as a preferred/common pattern (or aligning it explicitly with STYLE-GUIDE.md) rather than a requirement reviewers should enforce.
| - **Page ending pattern**: How-to guides and tutorials follow this closing pattern: Next steps > Related information > Troubleshooting (if applicable). "Next steps" contains 1-3 forward links to the next logical pages. Missing "Next steps" is a primary issue. | |
| - **Page ending pattern**: Per the style guide, pages should end with a **Next steps** section that links to 1–3 logical follow-on pages. A common closing pattern for how-to guides and tutorials is: Next steps, then Related information, and optionally Troubleshooting. Treat this as a preferred pattern (when it fits), but always flag missing **Next steps** as a primary issue. |
Minor refinement of the docs-review skill.
Signed-off-by: Dan Barr 6922515+danbarr@users.noreply.github.com