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 (L24-L32)
• Quick Start (L54-L90)
• Documentation Structure (L91-L128)
• Change Detection (L129-L152)
• References (L153-L161)
• Related Skills (L162-L169)

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

Related Skills

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.