RFC-37 Documentation Standardization

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

<!-- AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY --> <!-- Source: bitsoex/​ai-code-instructions → global/​skills/​rfc-37-documentation/​SKILL.md --> <!-- To modify, edit the source file and run the distribution workflow -->