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
[![Tests](https://img.shields.io/badge/tests-632_passing-success.svg)]
[![Version](https://img.shields.io/npm/v/@j0kz/mcp-agents.svg)]
[![License](https://img.shields.io/badge/license-MIT-blue.svg)]

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

[![npm version](https://img.shields.io/npm/v/@j0kz/mcp-agents.svg)](https://www.npmjs.com/package/@j0kz/mcp-agents)
[![Tests](https://img.shields.io/badge/tests-632_passing-success.svg)](https://github.com/j0KZ/mcp-agents/actions)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Downloads](https://img.shields.io/npm/dm/@j0kz/mcp-agents.svg)](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!