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

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

Only update when code changes
Preserve existing content if accurate
Don't rewrite just to rephrase
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.