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

📦 assets/ - Templates and resources

Quick Start

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

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

Create directory structure:

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

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

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

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:

Local Execution (docs/how-tos/local-execution.md)
- Use template: assets/local-execution.md.template
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

| Function | Description | |----------|-------------| | validate(dir) | Validate RFC-37 directory structure | | lint(dir) | Run full documentation linting | | checkLinterInstalled() | Check if doclinter is available | | generateTree(dir) | Generate Confluence tree preview |

References

| Reference | Description | |-----------|-------------| | references/rfc-37.md | RFC-37 summary and requirements | | references/validation-rules.md | All 10 linter rules with examples | | references/confluence-metadata.md | Confluence config (mark.toml, metadata) | | references/installation.md | Linter installation guide | | references/ai-fixes.md | AI-assisted documentation fixes |

Assets

| Asset | Description | |-------|-------------| | assets/mark.toml.template | Confluence config template | | assets/doclinterrc.yml.template | Linter config template | | assets/local-execution.md.template | Local execution doc template |

External Documentation

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

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