| 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
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
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.
