rfc-37-documentation

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

Sections

• [When to use this skill](#when-to-use-this-skill) (L19-L26)
• [Quick Start](#quick-start) (L58-L87)
• [Standard Directory Structure](#standard-directory-structure) (L88-L104)
• [Required Documentation](#required-documentation) (L105-L115)
• [Validation](#validation) (L116-L135)
• [Available Scripts](#available-scripts) (L136-L152)
• [References](#references) (L153-L162)
• [Assets](#assets) (L163-L170)
• [External Documentation](#external-documentation) (L171-L179)
• [Related Skills](#related-skills) (L180-L184)

Available Resources

📚 references/ - Detailed documentation

• [ai fixes](references/ai-fixes.md)
• [confluence metadata](references/confluence-metadata.md)
• [installation](references/installation.md)
• [rfc 37](references/rfc-37.md)
• [validation rules](references/validation-rules.md)

📦 assets/ - Templates and resources

• [doclinterrc.yml](assets/doclinterrc.yml.template)
• [local execution.md](assets/local-execution.md.template)
• [mark.toml](assets/mark.toml.template)

---

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

```bash

brew tap bitsoex/homebrew-bitso

brew install bitso-documentation-linter

```

1. Create directory structure:

```bash

mkdir -p docs/{decisions,how-tos,runbooks}

mkdir -p docs/my-service/{concepts,getting-started}

```

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

```bash

# Copy and edit the template

cp assets/mark.toml.template docs/mark.toml

```

1. Validate:

```bash

doclinter --repo-path . --verbose

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

```

```

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-specific docs

├── concepts/ # Architecture, design (required)

└── getting-started/ # Quick start (required)

```

Every service MUST have:

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

- Use template: [assets/local-execution.md.template](assets/local-execution.md.template)

1. Service Concepts (docs//concepts/)

- Architecture diagrams (C4 recommended)

- Key components and dependencies

Run the linter to check compliance:

```bash

# 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](references/validation-rules.md).

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

```bash

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

| Reference | Description |

|-----------|-------------|

| [references/rfc-37.md](references/rfc-37.md) | RFC-37 summary and requirements |

| [references/validation-rules.md](references/validation-rules.md) | All 10 linter rules with examples |

| [references/confluence-metadata.md](references/confluence-metadata.md) | Confluence config (mark.toml, metadata) |

| [references/installation.md](references/installation.md) | Linter installation guide |

| [references/ai-fixes.md](references/ai-fixes.md) | AI-assisted documentation fixes |

| Asset | Description |

|-------|-------------|

| [assets/mark.toml.template](assets/mark.toml.template) | Confluence config template |

| [assets/doclinterrc.yml.template](assets/doclinterrc.yml.template) | Linter config template |

| [assets/local-execution.md.template](assets/local-execution.md.template) | Local execution doc template |

The linter has extensive documentation at [github.com/bitsoex/bitso-documentation-linter](https://github.com/bitsoex/bitso-documentation-linter):

• [Local Execution Guide](https://github.com/bitsoex/bitso-documentation-linter/blob/main/docs/how-tos/local-execution.md)
• [Configuration Reference](https://github.com/bitsoex/bitso-documentation-linter/blob/main/docs/bitso-documentation-linter/concepts/configuration.md)
• [CLI Options](https://github.com/bitsoex/bitso-documentation-linter/blob/main/docs/bitso-documentation-linter/concepts/cli-options.md)
• [AI Fixes Guide](https://github.com/bitsoex/bitso-documentation-linter/blob/main/docs/how-tos/how-to-fix-documentation-using-ai.md)

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