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#

• Adding new features or functionality
• Changing API endpoints, methods, or interfaces
• Introducing breaking changes
• Modifying dependencies or requirements
• Changing configuration options or environment variables
• Updating installation or setup procedures
• Modifying CLI commands or scripts
• When code examples in documentation become outdated

Prerequisites#

• Understanding of the project's documentation structure
• Access to code changes being made
• Knowledge of documentation files that may need updates

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:

• New features (under "Added" section)
• Bug fixes (under "Fixed" section)
• Breaking changes (under "Changed" section with BREAKING prefix)
• Deprecated features (under "Deprecated" section)
• Removed features (under "Removed" section)
• Security fixes (under "Security" section)

Changelog format:

markdown

## [Version] - YYYY-MM-DD

### Added
- 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:

• README.md: Project overview, quick start, basic usage

• CHANGELOG.md: Version history and user-facing changes

• docs/: Detailed documentation

  • 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

• examples/: Working code examples and tutorials

Documentation Quality Standards#

Writing Guidelines#

• Use clear, concise language
• Include working code examples
• Provide both basic and advanced examples
• Use consistent terminology
• Include error handling examples
• Document edge cases and limitations

Code Example Format#

markdown

### 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#

markdown

### `functionName(param1, param2)`

Brief description of what the function does.

**Parameters:**
- `param1` (type): Description of parameter
- `param2` (type, optional): Description with default value

**Returns:**
- `type`: Description of return value

**Example:**
\`\`\`language
const result = functionName('value', 42);
\`\`\`

**Throws:**
- `ErrorType`: When and why error is thrown

Best Practices#

Do's#

• Update documentation in the same commit as code changes
• Include before/after examples for changes to be reviewed
• Test code examples before committing
• Use consistent formatting and terminology
• Document limitations and edge cases
• Provide migration paths for breaking changes
• Keep documentation DRY (link instead of duplicating)

Don'ts#

• Commit code changes without updating documentation
• Leave outdated examples in documentation
• Document features that don't exist yet
• Use vague or ambiguous language
• Forget to update changelog
• Ignore broken links or failing examples
• Document implementation details users don't need

Validation Commands#

Example scripts for documentation validation:

json

{
  "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:

• README.md reflects current project state
• All new features are documented
• Code examples are tested and work
• API documentation is complete and accurate
• Configuration examples are up to date
• Breaking changes are documented with migration guide
• CHANGELOG.md is updated
• Links are valid and not broken
• Installation instructions are current
• Environment variables are documented

Troubleshooting#

IssueSolutionOutdated code examplesRe-run examples against current code and updateMissing API documentationReview all public interfaces and document eachBroken linksUse link checker tools to identify and fixInconsistent terminologyCreate a glossary and standardize usageMissing changelog entryAdd entry following the changelog format