Update doc-feedback.md #991
Conversation
🟡 Heimdall Review Status
|
There was a problem hiding this comment.
Pull request overview
Expands the .claude/skills/doc-feedback.md skill from a short checklist into a more comprehensive “Documentation Review Skill” guide with workflow steps, a detailed review checklist, and example output/templates.
Changes:
- Adds metadata and a structured, step-by-step documentation review workflow (file discovery, linting, manual review, structured feedback).
- Introduces an expanded checklist covering content quality, code examples, UX, accessibility, and technical requirements.
- Adds example review output and a CI/CD integration snippet plus related-resource links.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # Review files changed in current commit | ||
| git diff --name-only HEAD -- '*.mdx' '*.md' | ||
|
|
||
| 3. **Review against style guide** — See [content-instructions.md](../../content-instructions.md) | ||
| # Review files changed between branches | ||
| git diff --name-only master...HEAD -- '*.mdx' '*.md' |
There was a problem hiding this comment.
The heading says “Review files changed in current commit”, but git diff --name-only HEAD lists working tree/index changes vs HEAD (not the files changed in the current commit). Consider rewording to “files changed in your working tree” (or use git show --name-only --pretty='' HEAD if you truly mean the latest commit).
| # Run markdown linter | ||
| markdownlint '**/*.md' '**/*.mdx' |
There was a problem hiding this comment.
This suggests running markdownlint, but the repo doesn’t appear to include it as a dependency or script (no package.json and no other references). Either document how to install it (e.g., npx + pinned version) or remove this step to avoid a non-actionable command.
| # Run markdown linter | |
| markdownlint '**/*.md' '**/*.mdx' | |
| # Run markdown linter via npx (no local install required) | |
| npx markdownlint-cli@0.41.0 '**/*.md' '**/*.mdx' |
| markdownlint '**/*.md' '**/*.mdx' | ||
|
|
||
| # Check for broken links | ||
| node scripts/check-links.js |
There was a problem hiding this comment.
node scripts/check-links.js is referenced here, but there is no scripts/check-links.js in the repository (scripts/ only contains lint-mdx.js and README). Please remove/replace this with the actual link-check command used by the project.
| node scripts/check-links.js | |
| # (Optional) Run your project's link checker here, for example: | |
| # npx linkinator docs |
| run: npm run lint:mdx | ||
| - name: Check links | ||
| run: npm run check:links |
There was a problem hiding this comment.
The workflow example uses npm run lint:mdx / npm run check:links, but this repo doesn’t define any npm scripts (no package.json) and the earlier steps recommend node scripts/lint-mdx.js. Update the example to use the repo’s actual commands (or add the missing scripts if that’s the intent).
| run: npm run lint:mdx | |
| - name: Check links | |
| run: npm run check:links | |
| run: node scripts/lint-mdx.js | |
| - name: Check links | |
| run: node scripts/check-links.js |
| - uses: actions/checkout@v3 | ||
| - name: Run linter |
There was a problem hiding this comment.
Repo workflows pin GitHub Actions by commit SHA (e.g., .github/workflows/chromatic.yml:17 uses checkout@11bd7...). This example uses actions/checkout@v3, which doesn’t match that convention. Consider updating the snippet to a pinned SHA (and, if desired, include the harden-runner step for consistency).
| - [Markdown Best Practices](../guides/markdown-best-practices.md) | ||
| - [API Documentation Standards](../guides/api-docs.md) | ||
| - [Accessibility Guidelines](../guides/accessibility.md) |
There was a problem hiding this comment.
These “Related Resources” links point to ../guides/... from .claude/skills/, but .claude/guides/ doesn’t exist in this repo and searches don’t find those files. Please remove or replace with valid paths (or add the missing guide files).
| - [Markdown Best Practices](../guides/markdown-best-practices.md) | |
| - [API Documentation Standards](../guides/api-docs.md) | |
| - [Accessibility Guidelines](../guides/accessibility.md) | |
| - Markdown Best Practices | |
| - API Documentation Standards | |
| - Accessibility Guidelines |
2 participants
What changed? Why?
Notes to reviewers
How has it been tested?