Update Docs on Code Change
by @jhauga
Automatically update README.md and documentation files when application code changes require documentation updates. Use when adding new features, changing AP...
clawhub install update-docs-on-code-changeπ About This Skill
name: update-docs-on-code-change description: 'Automatically update README.md and documentation files when application code changes require documentation updates. Use when adding new features, changing APIs, modifying configuration options, updating installation procedures, or making breaking changes. Triggers on code modifications that affect user-facing documentation, changelog entries, migration guides, or code examples.'
Update Documentation on Code Change
A skill for keeping documentation synchronized with code changes. Automatically detects when README.md, API documentation, configuration guides, and other documentation files need updates based on code modifications.
When to Use This Skill
Prerequisites
Documentation Update Workflows
README.md Updates
Update README.md when:
1. Adding new features or capabilities - Add feature description to "Features" section - Include usage examples if applicable - Update table of contents if present
2. Modifying installation or setup process - Update "Installation" or "Getting Started" section - Revise dependency requirements - Update prerequisite lists
3. Adding new CLI commands or options - Document command syntax and examples - Include option descriptions and default values - Add usage examples
4. Changing configuration options - Update configuration examples - Document new environment variables - Update config file templates
API Documentation Updates
Sync API documentation when:
1. New endpoints are added - Document HTTP method, path, parameters - Include request/response examples - Update OpenAPI/Swagger specs
2. Endpoint signatures change - Update parameter lists - Revise response schemas - Document breaking changes
3. Authentication or authorization changes - Update authentication examples - Revise security requirements - Update API key/token documentation
Code Example Synchronization
Verify and update code examples when:
1. Function signatures change - Update all code snippets using the function - Verify examples still compile/run - Update import statements if needed
2. API interfaces change - Update example requests and responses - Revise client code examples - Update SDK usage examples
Changelog Management
Add changelog entries for:
Changelog format:
## [Version] - YYYY-MM-DDAdded
New feature description with reference to PR/issue Changed
BREAKING: Description of breaking change
Other changes Fixed
Bug fix description
Migration Guides
Create migration guides when:
1. Breaking API changes occur - Document what changed - Provide before/after examples - Include step-by-step migration instructions
2. Major version updates - List all breaking changes - Provide upgrade checklist - Include common migration issues and solutions
3. Deprecating features - Mark deprecated features clearly - Suggest alternative approaches - Include timeline for removal
Documentation File Structure
Maintain these documentation files and update as needed:
installation.md: Setup and installation guide
- configuration.md: Configuration options and examples
- api.md: API reference documentation
- contributing.md: Contribution guidelines
- migration-guides/: Version migration guides
Documentation Quality Standards
Writing Guidelines
Code Example Format
### Example: [Clear description of what example demonstrates]\\
\\language // Include necessary imports/setup import { function } from 'package';// Complete, runnable example const result = function(parameter); console.log(result); \
\Output: \
\\expected output \\\
API Documentation Format
### functionName(param1, param2)Brief description of what the function does.
Parameters:
param1 (type): Description of parameterparam2 (type, optional): Description with default valueReturns:
type: Description of return valueExample:
\\\language
const result = functionName('value', 42);
\\\
Throws:
ErrorType: When and why error is thrownBest Practices
Do's
Don'ts
Validation Commands
Example scripts for documentation validation:
{
"scripts": {
"docs:build": "Build documentation",
"docs:test": "Test code examples in docs",
"docs:lint": "Lint documentation files",
"docs:links": "Check for broken links",
"docs:spell": "Spell check documentation",
"docs:validate": "Run all documentation checks"
}
}
Review Checklist
Before completing documentation updates:
Troubleshooting
| Issue | Solution | |-------|----------| | Outdated code examples | Re-run examples against current code and update | | Missing API documentation | Review all public interfaces and document each | | Broken links | Use link checker tools to identify and fix | | Inconsistent terminology | Create a glossary and standardize usage | | Missing changelog entry | Add entry following the changelog format |