doc-generation-rfc-37

name	doc-generation-rfc-37
description	Generate and update AI-friendly documentation for services following RFC-37 templates. Produces concepts/, features/, getting-started/ content with Mermaid diagrams and C4 architecture. Use when generating or updating service documentation.
compatibility	All services following Bitso patterns; enhanced for Java services
metadata	{"version":"1.0.0","rfc":"RFC-37","category":"documentation","tags":["documentation","rfc-37","generation","rag"]}

RFC-37 Documentation Generation

Generate RFC-37 compliant documentation for services in this repository.

When to use this skill

• Generating documentation for new services
• Updating documentation after code changes
• Setting up documentation structure for a repository
• Creating feature and concept documentation
• Integrating with RAG systems
• When asked to "generate documentation" or "create docs"

Skill Contents

Sections

• When to use this skill
• Quick Start
• Documentation Structure
• Change Detection
• References
• Related Skills

Available Resources

📚 references/ - Detailed documentation

• atlas mcp usage
• documentation workflow
• templates
• troubleshooting

---

Quick Start

1. Identify Services

Scan bitso-services/ directory for deployable services:

ls -d bitso-services/*/

Each subdirectory is a separate service to document.

2. Create Documentation Structure

docs/
├── README.md                    # Repository overview
└── <service-name>/              # One folder per service
    ├── overview.md              # Business purpose
    ├── architecture.md          # Dependencies, data flow
    ├── concepts/                # Domain concepts
    │   └── <concept>.md
    └── features/                # Feature documentation
        └── <feature>.md

3. Use Templates

Apply RFC-37 templates from references/templates.md or refer to the comprehensive doc-validation-rfc-37 skill for:

• Directory structure requirements
• Confluence metadata configuration
• Documentation linting and validation

4. Run with Idempotency

Only update documentation when code changes. Check existing docs first.

Documentation Structure

Service-Specific Focus

Document only service-specific information:

✅ Document:

• Business purpose and domain concepts
• Service architecture and dependencies
• Features and use cases
• gRPC APIs and contracts
• Data models (PostgreSQL, Redis)

❌ Don't Document (covered in platform docs):

• General local development setup
• Testing patterns
• Monitoring and logging
• Standard architecture patterns
• Deployment processes

Folder Structure

docs/
├── api/                         # Human-managed
├── decisions/                   # Human-managed
├── runbooks/                    # Human-managed
└── <service-name>/              # AI-managed
    ├── overview.md
    ├── architecture.md
    ├── concepts/
    │   ├── <concept-1>.md
    │   └── <concept-2>.md
    └── features/
        ├── <feature-1>.md
        └── <feature-2>.md

Change Detection

Idempotency Rules

1. Only update when code changes
2. Preserve existing content if accurate
3. Don't rewrite just to rephrase
4. Don't change formatting if content is accurate

What Constitutes a Change

UPDATE documentation when:

• New features or concepts added
• Architecture changes
• API contracts change
• Database schema changes
• Business rules change

DON'T update when:

• Code formatting changes
• Variable names change but behavior is same
• Tests modified but functionality unchanged
• Internal refactoring without API changes

References

Reference	Description
references/atlas-mcp-usage.md	MCP queries for Atlas
references/documentation-workflow.md	Full generation workflow
references/templates.md	RFC-37 document templates
references/troubleshooting.md	Common issues and solutions

Related Skills

Skill	Purpose
doc-validation-rfc-37	RFC-37 structure validation, linting, Confluence config
quality-checks	Quality gate orchestration

Note: For RFC-37 compliance validation and Confluence mirroring setup, use the doc-validation-rfc-37 skill. This skill focuses on AI-assisted content generation.