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

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:

• 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