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

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

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!