| name | docs-codebase |
| description | Technical writing patterns for README files, API documentation, architecture decision records (ADRs), changelogs, contributing guides, code comments, and docs-as-code workflows. Covers documentation structure, style guides, Markdown best practices, and documentation testing. |
Technical Documentation — Quick Reference
This skill provides execution-ready patterns for writing clear, maintainable technical documentation. Claude should apply these patterns when users need README files, API docs, ADRs, changelogs, or any technical writing.
Modern Best Practices (2025): Docs-as-code workflows, Markdown standardization, automated changelog generation, ADRs, interactive API docs (OpenAPI 3.2+), documentation testing, accessibility standards (WCAG 2.2), and docs in version control with CI/CD.
When to Use This Skill
Claude should invoke this skill when a user requests:
- Writing README files for projects
- Documenting APIs (REST, GraphQL, gRPC)
- Creating architecture decision records (ADRs)
- Writing changelogs and release notes
- Creating contributing guidelines
- Documenting code with comments and docstrings
- Setting up docs-as-code workflows
- Creating user guides and tutorials
- Writing technical specifications
- Building documentation sites (MkDocs, Docusaurus)
Quick Reference
| Documentation Type | Template | Key Sections | When to Use |
|---|
| Project README | readme-template.md | Name, Features, Installation, Usage, Config | New project, open source, onboarding |
| Architecture Decision | adr-template.md | Status, Context, Decision, Consequences | Technical decisions, trade-offs |
| API Reference | api-docs-template.md | Auth, Endpoints, Schemas, Errors, Rate Limits | REST/GraphQL APIs, webhooks |
| Changelog | changelog-template.md | Added, Changed, Deprecated, Removed, Fixed, Security | Releases, version history |
| Contributing Guide | contributing-template.md | Setup, Commit Guidelines, PR Process, Code Style | Open source, team projects |
| Code Comments | JSDoc, Python docstrings | Params, Returns, Raises, Examples | Public APIs, complex functions |
| User Guide | MkDocs/Docusaurus | Getting Started, Tutorials, Troubleshooting | End-user documentation |
Decision Tree: Choosing Documentation Type
User needs: [Documentation Task]
├─ New project or repository?
│ └─ **README.md** (project overview, installation, quick start)
│
├─ Made important technical decision?
│ ├─ Architecture or design choice? → **ADR** (adr-template.md)
│ └─ Technology choice? → **ADR** with alternatives section
│
├─ Building or documenting API?
│ ├─ REST API? → **OpenAPI 3.1** spec + api-docs-template
│ ├─ GraphQL API? → Schema-first + GraphQL Docs
│ └─ gRPC API? → Protobuf + generated docs
│
├─ Releasing new version?
│ ├─ Manual changelog? → **CHANGELOG.md** (Keep a Changelog format)
│ └─ Automated? → semantic-release + Conventional Commits
│
├─ Open source or team collaboration?
│ ├─ Contribution workflow? → **CONTRIBUTING.md**
│ ├─ Code of conduct? → CODE_OF_CONDUCT.md
│ └─ License? → LICENSE file
│
├─ Documenting code?
│ ├─ Public API/library? → **Docstrings** (JSDoc, Python, etc.)
│ ├─ Complex logic? → **Comments** (explain WHY, not WHAT)
│ └─ Architecture? → **README** in module/package + diagrams
│
├─ Building documentation site?
│ ├─ Python project? → **MkDocs** + Material theme
│ ├─ JavaScript/React? → **Docusaurus** (versioning support)
│ └─ Next.js? → **Nextra** (minimal setup)
│
└─ Troubleshooting guide?
└─ Common issues → Solutions → Diagnostic commands → Logs location
Navigation: README Documentation
README Best Practices - resources/readme-best-practices.md
Comprehensive guide for creating effective README files with:
- Essential 13-section structure (Name, Features, Prerequisites, Installation, Configuration, Usage, etc.)
- Copy-paste ready installation commands
- Configuration table templates
- Troubleshooting patterns
- Badge recommendations
- Anti-patterns to avoid
- README quality checklist
When to use: Creating new project README or improving existing documentation.
Navigation: Architecture Documentation
ADR Writing Guide - resources/adr-writing-guide.md
Complete guide for documenting architectural decisions with:
- 8-section ADR structure (Title, Status, Context, Decision, Consequences, Alternatives, Implementation, References)
- Status lifecycle (Proposed → Accepted → Deprecated → Superseded)
- How to document trade-offs and alternatives
- ADR naming conventions and indexing
- When to write vs skip ADRs
- Real-world examples with metrics
When to use: Documenting technical decisions like database choice, framework selection, or architecture patterns.
Template: templates/architecture/adr-template.md
Navigation: Changelog Documentation
Changelog Best Practices - resources/changelog-best-practices.md
Guide for maintaining changelogs using Keep a Changelog format with:
- 6 change categories (Added, Changed, Deprecated, Removed, Fixed, Security)
- Semantic versioning rules (MAJOR.MINOR.PATCH)
- Unreleased section management
- Conventional Commits integration
- Automated changelog generation (semantic-release, standard-version)
- Breaking change communication
- Linking to Git commits
When to use: Creating release notes, maintaining version history, documenting breaking changes.
Template: templates/project-management/changelog-template.md
Navigation: API Documentation
API Documentation Standards - resources/api-documentation-standards.md
Modern API documentation standards covering:
- REST API documentation (OpenAPI 3.1/3.2, authentication, endpoints, errors)
- GraphQL API documentation (schema, queries, mutations)
- gRPC API documentation (Protocol Buffers, service definitions)
- Essential elements (base URL, auth, rate limiting, pagination, webhooks)
- Error response format (RFC 7807)
- Interactive documentation tools (Swagger UI, Redoc, Stoplight)
- Code examples in multiple languages
When to use: Documenting REST, GraphQL, or gRPC APIs for developers.
Template: templates/api-reference/api-docs-template.md
Navigation: Code Comments & Docstrings
Code Commenting Guide - resources/code-commenting-guide.md
Comprehensive guide for effective code documentation with:
- Core principles (Comment WHY not WHAT, avoid obvious comments, keep updated)
- Docstring formats (JSDoc, Python Google Style, TSDoc, Godoc)
- Inline comment best practices
- When to use documentation vs implementation comments
- Comment anti-patterns (commented-out code, redundant comments, changelog comments)
- TODO/FIXME/HACK comment standards
- Accessibility comments (ARIA labels)
When to use: Documenting code for maintainability, writing public API documentation.
Navigation: Contributing Guidelines
Contributing Guide Standards - resources/contributing-guide-standards.md
Guide for creating CONTRIBUTING.md files with:
- 9-section structure (Welcome, Ways to Contribute, Setup, Workflow, Code Style, Review, Issues, Community, Recognition)
- Development setup instructions
- Conventional Commits format
- Pull request workflow
- Code style guidelines (JavaScript, Python, testing)
- Code review expectations
- Bug reporting and feature request templates
- Security vulnerability reporting
When to use: Setting up contribution process for open-source or team projects.
Template: templates/project-management/contributing-template.md
Navigation: Docs-as-Code Workflows
Docs-as-Code Setup - resources/docs-as-code-setup.md
Setting up documentation with version control and CI/CD:
- MkDocs configuration and Material theme
- Docusaurus setup for versioned docs
- GitBook integration
- GitHub Actions for automated deployment
- Documentation site structure
- Search and navigation patterns
When to use: Building documentation sites with automated deployment.
Navigation: Writing & Testing
Technical Writing Best Practices - resources/writing-best-practices.md
Clear communication principles:
- Active voice and conciseness
- Plain language guidelines
- Audience awareness
- Structure and formatting
- Writing style consistency
Markdown Style Guide - resources/markdown-style-guide.md
Markdown formatting standards:
- Syntax reference (headers, lists, code blocks, tables)
- Style consistency rules
- Link formatting
- Code block language tags
- Table formatting
Documentation Testing - resources/documentation-testing.md
Automated documentation quality checks:
- Linting with markdownlint and Vale
- Link validation with markdown-link-check
- Spell checking with cspell
- Code example testing
- CI/CD integration
When to use: Establishing documentation standards, automating quality checks.
Templates
Complete copy-paste ready templates organized by domain:
Architecture Documentation
API Reference
Project Management
Docs-as-Code
Do / Avoid (Dec 2025)
Do
- Assign owners and review cadences to docs that matter (runbooks, onboarding, APIs).
- Add CI checks for links, style, and stale docs where feasible.
- Prefer small, task-oriented docs over “big wiki pages”.
Avoid
- Docs without owners (guaranteed to rot).
- Stale runbooks (dangerous during incidents).
- Copy/paste docs that drift from code and config.
What Good Looks Like
- Ownership: every critical doc has an owner and review cadence (runbooks, onboarding, APIs).
- Structure: consistent information architecture (tutorial/how-to/reference/explanation) and clear navigation.
- Quality gates: CI runs link checks and linting; stale docs are flagged.
- Decision capture: ADRs exist for major choices and are referenced from code and runbooks.
- Onboarding: a new engineer can get to a first PR within a defined target time (tracked and improved).
Optional: AI / Automation
Use only when explicitly requested and policy-compliant.
- Draft and summarize docs changes; humans review before publishing.
- Generate doc diffs in PRs; do not auto-merge.
External Resources
See data/sources.json for:
- Style Guides: Google Developer Docs, Microsoft Writing Guide, Write the Docs
- Documentation Tools: MkDocs, Docusaurus, GitBook, Nextra, Mintlify
- API Documentation: OpenAPI, Swagger UI, Redoc, GraphQL Docs
- Testing Tools: Vale (prose linting), markdownlint, cspell (spell check), markdown-link-check
- Patterns: Keep a Changelog, Semantic Versioning, ADRs, Conventional Commits
- Learning: Google Technical Writing Courses, Docs for Developers (book)
Related Skills
Navigation: Production Gotchas Documentation
Purpose: Document platform-specific issues, silent failures, and hard-to-debug problems to prevent repeated mistakes.
When to Use: After discovering a production issue that:
- Took significant time to debug
- Was caused by external service configuration (not your code)
- Could affect other developers on the team
- Has a non-obvious solution
Gotcha Documentation Structure
## Production Gotchas
### [Provider/Feature Name]
- **The Trap**: What looks correct but actually fails
- **Symptom**: How the issue manifests (error messages, behavior)
- **Root Cause**: Why it happens (the underlying reason)
- **Fix**: Step-by-step solution
- **Prevention**: How to avoid this in the future
Example Gotchas (Real-World)
## Production Gotchas
### Vercel Cron Jobs Require Pro Plan
- **The Trap**: Cron configuration in vercel.json looks valid, jobs never run
- **Symptom**: Scheduled tasks (notifications, data cleanup) never execute; no errors in logs
- **Root Cause**: Vercel Free tier doesn't support cron jobs; requires Pro plan ($20/month)
- **Fix**: Upgrade to Vercel Pro, verify cron jobs in Vercel dashboard under "Cron Jobs" tab
- **Prevention**: Check Vercel plan requirements before implementing scheduled features
### Supabase Site URL Misconfiguration
- **The Trap**: OAuth redirects users to localhost instead of production domain
- **Symptom**: Users click "Sign in with Google" → redirected to localhost:3000 → broken auth
- **Root Cause**: Site URL in Supabase Dashboard → Authentication → URL Configuration still set to localhost
- **Fix**: Set Site URL to `https://your-production-domain.com` (no trailing slash)
- **Prevention**: Add Site URL configuration to deployment checklist
### Apple OAuth Secret Expiration
- **The Trap**: Apple Sign-In stops working after 6 months with no warning
- **Symptom**: "Invalid client secret" error on Apple OAuth flow
- **Root Cause**: Apple's client secret JWT expires in 180 days (not documented clearly)
- **Fix**: Regenerate client secret using .p8 key: `npm run generate-apple-secret`
- **Prevention**: Set calendar reminder 7 days before expiration; consider automation
### Next.js API Route JSON Parsing
: API returns 500 error when client sends malformed JSON
: in server logs; client sees generic 500
: throws if body isn't valid JSON
: Wrap in try-catch, return 400 with helpful message
: Create reusable utility (see software-backend skill)
Where to Document Gotchas
| Project Type | Location | Format |
|---|
| Claude Code projects | CLAUDE.md | Markdown section |
| Standard projects | docs/gotchas.md or TROUBLESHOOTING.md | Dedicated file |
| Wiki/Notion | Dedicated page | Searchable knowledge base |
| README | Bottom section | Brief summaries with links |
Gotcha Documentation Checklist
[ ] Gotcha has clear, searchable title
[ ] Symptom describes what user sees (error messages, behavior)
[ ] Root cause explains WHY (not just WHAT)
[ ] Fix has step-by-step instructions
[ ] Prevention explains how to avoid in future
[ ] Added to project documentation
[ ] Shared with team (Slack, standup, PR comment)
Anti-Patterns
- Too vague: "Sometimes auth breaks" → Add specific error messages and conditions
- Missing root cause: "Set Site URL to production" → Explain WHY this matters
- No prevention: Fix alone isn't enough → How to avoid this next time?
- Buried in code comments: Gotchas should be discoverable, not hidden in code
Usage Notes
For Claude: When a user requests documentation:
- Identify documentation type using the Decision Tree
- Reference appropriate template from templates/ directory
- Follow best practices from relevant resource file
- Provide copy-paste ready content with user's specific context
- Include examples from templates or resources
- Mention related skills if user might need complementary guidance
Common workflows:
- New project: README template → Contributing guide → Changelog
- API development: API docs template → OpenAPI spec → Interactive docs
- Technical decision: ADR template → Document alternatives → Reference in README
- Open source setup: README → CONTRIBUTING.md → CODE_OF_CONDUCT.md → LICENSE
Quality checks:
- Verify all links work (use markdown-link-check)
- Run spell checker (cspell)
- Lint Markdown (markdownlint)
- Test code examples actually run
- Check accessibility (WCAG 2.2 for web docs)
Success Criteria: Documentation is clear, accurate, up-to-date, discoverable, and enables users to be productive quickly with minimal support.
