rfc-37-documentation

RFC-37 Documentation Standardization

Implements RFC-37 for standardized markdown documentation that mirrors to Confluence.

When to use this skill

• Creating documentation for a new service
• Validating existing documentation structure
• Fixing documentation linting violations
• Setting up Confluence mirroring configuration
• Understanding documentation requirements

Skill Contents

Sections

• When to use this skill (L19-L26)
• Quick Start (L58-L87)
• Standard Directory Structure (L88-L104)
• Required Documentation (L105-L115)
• Validation (L116-L135)
• Available Scripts (L136-L152)
• References (L153-L162)
• Assets (L163-L170)
• External Documentation (L171-L179)
• Related Skills (L180-L184)

Available Resources

📚 references/ - Detailed documentation

• ai fixes
• confluence metadata
• installation
• rfc 37
• validation rules

📦 assets/ - Templates and resources

• doclinterrc.yml
• local execution.md
• mark.toml

Quick Start

1. Install the linter (see references/installation.md):

   brew tap bitsoex/homebrew-bitso
   brew install bitso-documentation-linter
   

2. Create directory structure:

   mkdir -p docs/{decisions,how-tos,runbooks}
   mkdir -p docs/my-service/{concepts,getting-started}
   

3. Create Confluence config (see references/confluence-metadata.md):

   # Copy and edit the template
   cp assets/mark.toml.template docs/mark.toml
   

4. Validate:

   doclinter --repo-path . --verbose
   doclinter tree --repo-path .  # Preview Confluence hierarchy
   

Standard Directory Structure

docs/
├── api/                    # API documentation
│   ├── async/              # Event-driven APIs
│   ├── grpc/               # gRPC APIs
│   └── rest/               # REST APIs
├── decisions/              # Architecture Decision Records (required)
├── how-tos/                # Step-by-step guides (required)
│   └── local-execution.md  # REQUIRED for all services
├── runbooks/               # Operational procedures (required)
└── <service-name>/         # Service-specific docs
    ├── concepts/           # Architecture, design (required)
    └── getting-started/    # Quick start (required)

Required Documentation

Every service MUST have:

1. Local Execution (docs/how-tos/local-execution.md)

   • Use template: assets/local-execution.md.template

2. Service Concepts (docs/<service>/concepts/)

   • Architecture diagrams (C4 recommended)
   • Key components and dependencies

Validation

Run the linter to check compliance:

# Basic validation
doclinter --repo-path .

# Verbose with metrics
doclinter --repo-path . --verbose

# Preview Confluence tree
doclinter tree --repo-path .

# With Confluence API validation
CONFLUENCE_ENABLED=true doclinter --repo-path .

For full validation rules, see references/validation-rules.md.

Available Scripts

Scripts are implemented in .scripts/lib/skills/rfc-37.ts:

# Via skills CLI
node .scripts/skills-cli.ts rfc-37 validate
node .scripts/skills-cli.ts rfc-37 lint

References

Assets

External Documentation

The linter has extensive documentation at github.com/bitsoex/bitso-documentation-linter:

• Local Execution Guide
• Configuration Reference
• CLI Options
• AI Fixes Guide

Related Skills

• agent-hooks - For integrating linting into IDE hooks
• quality-gateway - For comprehensive quality checks
• doc-sync - For keeping docs in sync with code