j0KZ Documentation Patterns for @j0kz/mcp-agents
Complete guide to documentation generation and maintenance across the monorepo.
When to Use This Skill
- Creating README.md for new packages
- Updating CHANGELOG.md with release notes
- Maintaining API documentation
- Synchronizing GitHub wiki
- Updating badges (version, tests, coverage)
- Writing installation instructions
Evidence Base
Current State:
- 9 package READMEs (150-323 lines each)
- Consistent structure: badges, installation, features, examples
- CHANGELOG.md (1000+ lines) with 25+ releases
- docs/ folder with organized documentation
- Wiki synchronization workflow (publish-wiki.ps1)
Quick Commands
Generate Documentation
# Generate README for package
npx @j0kz/doc-generator@latest generate readme --package=smart-reviewer-mcp
# Generate API docs from TypeScript
npx @j0kz/doc-generator@latest generate api --input=src --output=docs/api
# Update CHANGELOG
npx @j0kz/doc-generator@latest generate changelog --version=1.0.36
Update Badges
# Update test count badge (automated)
npm run update:test-count
# Manual badge update in README
[]
[]
[]
Documentation Templates
For comprehensive templates and examples:
cat .claude/skills/documentation-generation/references/documentation-templates.md
Quick README Template
# Package Name
Brief description of what this package does.
## Installation
\`\`\`bash
npm install @j0kz/package-name
\`\`\`
## Usage
\`\`\`typescript
import { Tool } from '@j0kz/package-name';
const tool = new Tool();
const result = await tool.execute();
\`\`\`
## Features
- ✅ Feature 1
- ✅ Feature 2
- ✅ Feature 3
## API Reference
See [API Documentation](./docs/api.md)
## License
MIT
CHANGELOG Management
Conventional Format
## [1.0.36] - 2025-10-30
### Added
- New feature description
- Another new capability
### Changed
- Updated existing feature
- Modified behavior
### Fixed
- Bug fix description
- Another fix
### Performance
- Optimization description
Release Notes Automation
# Generate release notes from commits
git log --pretty=format:"- %s" v1.0.35..HEAD | grep -E "^- (feat|fix|perf):"
# Update version in CHANGELOG
sed -i "s/## \[Unreleased\]/## [1.0.36] - $(date +%Y-%m-%d)/" CHANGELOG.md
Badge Management
For complete badge reference and management:
cat .claude/skills/documentation-generation/references/badge-management-guide.md
Standard Badge Set
[](https://www.npmjs.com/package/@j0kz/mcp-agents)
[](https://github.com/j0KZ/mcp-agents/actions)
[](LICENSE)
[](https://npmjs.com/package/@j0kz/mcp-agents)
Wiki Synchronization
For detailed wiki sync guide:
cat .claude/skills/documentation-generation/references/wiki-sync-guide.md
Quick Sync
# Run from PowerShell on Windows
powershell.exe -File publish-wiki.ps1
# Manual sync
cd wiki
git add .
git commit -m "docs: sync wiki with main updates"
git push
API Documentation
Generate from TypeScript
# Using TypeDoc
npx typedoc --out docs/api src/index.ts
# Using doc-generator tool
npx @j0kz/doc-generator@latest generate api \
--input=src \
--output=docs/api \
--format=markdown
API Doc Structure
# API Reference
## Classes
### ClassName
Description of the class.
#### Constructor
\`\`\`typescript
new ClassName(options?: Options)
\`\`\`
#### Methods
##### methodName(param: Type): ReturnType
Description of what the method does.
**Parameters:**
- `param` (Type): Description
**Returns:** Description of return value
**Example:**
\`\`\`typescript
const result = instance.methodName('value');
\`\`\`
Documentation Standards
Writing Style
- Clear and concise - Avoid jargon
- Example-driven - Show, don't just tell
- Consistent formatting - Use templates
- Version-specific - Note breaking changes
- Searchable - Use descriptive headings
Required Sections
Every package README must have:
- Installation instructions
- Usage examples
- Feature list
- API reference or link
- License information
Code Examples
// ✅ GOOD: Complete, runnable example
import { SmartReviewer } from '@j0kz/smart-reviewer-mcp';
const reviewer = new SmartReviewer();
const result = await reviewer.reviewFile('src/index.ts');
console.log(result.issues);
// ❌ BAD: Incomplete, won't run
reviewer.review(); // Missing imports, incomplete
Automated Documentation
CI/CD Integration
# .github/workflows/docs.yml
name: Documentation
on:
push:
branches: [main]
jobs:
update-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Update test count
run: npm run update:test-count
- name: Generate API docs
run: npx typedoc
- name: Commit changes
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add -A
git commit -m "docs: auto-update documentation" || true
git push
Best Practices
- Keep README under 500 lines - Link to detailed docs
- Update CHANGELOG immediately - Don't wait for release
- Test all code examples - They should actually work
- Use semantic versioning - Major.Minor.Patch
- Include screenshots - For UI features
- Document breaking changes - In CHANGELOG and README
- Maintain consistent structure - Use templates
- Cross-reference docs - Link between related pages
- Version your docs - Tag documentation with releases
- Automate where possible - Badges, test counts, API docs
Complete Example Workflow
# 1. Update version
npm run version:sync
# 2. Update CHANGELOG
echo "## [1.0.36] - $(date +%Y-%m-%d)" >> CHANGELOG.md
echo "### Added" >> CHANGELOG.md
echo "- New feature X" >> CHANGELOG.md
# 3. Update test count
npm run update:test-count
# 4. Generate API docs
npx typedoc --out docs/api src/index.ts
# 5. Sync to wiki
powershell.exe -File publish-wiki.ps1
# 6. Commit everything
git add -A
git commit -m "docs: update for v1.0.36 release"
git push
Verification: Check README.md shows 632+ tests and version 1.0.36!