docs: add documentation style guide for AI agents #21153
Conversation
.claude/docs/DOCS_STYLE_GUIDE.md
Outdated
| ```json | ||
| { | ||
| "title": "Template Insights", | ||
| "description": "Monitor template usage and application metrics", | ||
| "path": "./admin/templates/template-insights.md" | ||
| } | ||
| ``` |
There was a problem hiding this comment.
We don't need to specify a spec... The agent should read it. Just make it clear that is a key step.
1ea8ea8 to
c695a1f
Compare
Add comprehensive documentation style guide in .claude/docs/ directory following the format established in PR #21148 for PR_STYLE_GUIDE.md. This guide captures observed patterns from existing Coder documentation including: - Research requirements before writing (code verification, permissions, thresholds) - Document structure and organization patterns - Image usage and screenshot guidelines - Writing style and terminology conventions - Code examples and formatting standards - Documentation manifest requirements - Accuracy standards for specific numbers, permissions, and API endpoints - Proactive documentation approach for upcoming features 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
c695a1f to
c52450e
Compare
matifali
left a comment
There was a problem hiding this comment.
Left a few suggestions that I think will make it more effective.
Addresses @matifali's feedback that Premium features also need a premium badge in manifest.json with "state": ["premium"]. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
Added clarification that Premium features also need |
Addresses @matifali's feedback: - Added mention of using tabs for related but parallel documentation paths - Added 'Formatting and Linting' section with make fmt/markdown and make lint/markdown commands 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
Addressed remaining feedback:
Re: SKILL.md suggestion - I've kept this in |
|
@matifali if we want to do skill.md which i am in favor of lets do that in a new PR after some testing |
david-fraley
left a comment
There was a problem hiding this comment.
Looks good, so approving as not to block (I'd rather get this out and iterate 😄 ). Some thoughts
- I think a comment around the redirects file not working would be good -- #21144
|
|
||
| Before documenting a feature: | ||
|
|
||
| 1. **Research similar documentation** - Read 10+ similar pages in `docs/` to understand writing style, structure, and conventions for your content type (admin guides, tutorials, reference docs, etc.) |
There was a problem hiding this comment.
Maybe tell it to focus on pages that have had recent commits? The "style" will likely shift as I (and whoever else) continue to author and update more pages. Otherwise, we can point it to specific pages and say use these + 5 others you think are are relevant
There was a problem hiding this comment.
It might also make sense to add somewhere "reference the Coder registry" as we've got a lot of cross links there
Adds a comprehensive documentation style guide in
.claude/docs/DOCS_STYLE_GUIDE.mddocumenting patterns observed across Coder's existing documentation. This guide is intended for AI agents to reference when writing documentation, ensuring consistency with project conventions.The guide covers research requirements (code verification, permissions model, UI thresholds), document structure (titles, premium callouts, overview sections), image usage (placement, captions, screenshot-driven organization), content organization, writing style, code examples, accuracy standards (specific numbers, permission actions, API endpoints), manifest requirements, and proactive documentation approaches.
Placed in
.claude/docs/alongside other agent-specific documentation (WORKFLOWS.md, ARCHITECTURE.md, etc.) and imported in CLAUDE.md to ensure it's automatically loaded into context for documentation work.🤖 Generated with Claude Code
Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com