Documentation Style Guide

This guide defines how Connectum documentation is written and structured so that every package README, every example, and every page on the documentation site reads consistently and stays accurate against the published source.

It has three parts:

1. Package README template — the canonical structure for the 15 @connectum/* package READMEs.
2. Documentation site pages — VitePress conventions for docs/en/**.
3. Content accuracy rules — the non-negotiable rules that keep docs true to the code.

The over-arching principle: the source code is the oracle. Documentation describes what the published 1.0.0 packages actually do — verified against src/index.ts, real signatures, and package.json — never against assumptions, older drafts, or test fixtures.

Package README template

Every published package README follows the same skeleton. Reshape the container to this order; keep the verified technical prose.

Canonical section order

# @connectum/<name>

<one-line summary>

**@connectum/<name>** is <bold description paragraph>.

## Features
## Installation
## Quick Start
## API Reference          ← always this exact heading (not "API" / "Main Exports")
## How It Works           (optional)
## Configuration / Types  (optional)
## Examples               (optional)
## Dependencies
## Requirements
## Documentation
## License

---

**Part of [@connectum](../../README.md)** — Universal framework for production-ready gRPC/ConnectRPC microservices

Package-specific sections (for example Interceptor Chain Order, External AMQP Contract, Performance Characteristics) are welcome — place them after Quick Start and before Dependencies.

Mandatory elements

Every published package README must have:

• Title # @connectum/<name>, a one-line summary, and a bold description intro.
• An Installation snippet (pnpm add @connectum/<name>; dev tools use pnpm add -D).
• A Quick Start with a runnable snippet.
• An API Reference section (named exactly that).
• Dependencies, Requirements, and License sections.
• The Part of [@connectum] footer (see below).

Internal/private helper packages (for example @connectum/test-fixtures) may use a reduced template, but should still carry the License line and footer.

Formatting conventions

• No image badges. None of the packages use shields; keep it that way for uniformity. Metadata (Layer / Node.js / License) may be a plain bold line under the title.
• Footer uses an em-dash, not a single hyphen. The repository writes em-dashes two ways and both are accepted in footers: the ASCII -- form used throughout the prose, or a real — (—). Pick one and avoid -: **Part of [@connectum](../../README.md)** -- Universal framework ....
• License is Apache-2.0 everywhere (see Content accuracy rules).
• Prefer pointing to the API Reference for the full export list over hand-enumerating every export — exhaustive tables drift the moment the surface changes. List the load-bearing symbols; link the rest.

@connectum/events-kafka is the cleanest exemplar of this template for adapter packages; @connectum/core for foundational packages.

Documentation site pages

The site is VitePress. Pages live under docs/en/**. The docs/en/api/** tree is auto-generated by TypeDoc (pnpm docs:api) — never hand-edit it.

Page conventions

• Frontmatter. Each page starts with a title:. The home page uses layout: home.

• Internal links are absolute, root-relative, and start with /en/:[Quick Start](/en/guide/quickstart). Do not link .md files relatively and do not include the .md extension. Verify every link resolves to a real page.

• Code groups for multi-file / multi-runtime examples:

  ::: code-group
  ```typescript [server.ts]
  // ...
  ```
  ```bash [cli]
  # ...
  ```
  :::

• Admonitions for callouts: ::: tip, ::: warning, ::: danger, ::: info.

• Heading levels. One # H1 per page (or the title: frontmatter); use ## / ### for structure. Keep heading text in sync with the sidebar label.

• Package layer statements must match the architecture map (Layer 0 / 1 / 2). Do not state a different layer on a package page than the canonical map.

Where things go

Content	Location
Conceptual guides	docs/en/guide/**
Per-package overview	docs/en/packages/<name>.md
Architecture decisions	docs/en/contributing/adr/**
Migration notes	docs/en/migration/**
Auto-generated API reference	docs/en/api/** (generated — do not edit)

When you add a page, register it in the sidebar in docs/.vitepress/config/en.ts.

Content accuracy rules

These rules are non-negotiable — a documentation contract break is a production defect for the consumer who follows the docs instead of the code.

1. Verify every symbol against source. Every function, option, field, default, and enum value named in the docs must exist with that shape in connectum/packages/<pkg>/src (and package.json). No phantom options, no removed APIs (ServiceRoute, Runner(), service-routing fallback were removed — see ADR-028).
2. Check code-example blocks, not just prose and tables. Drift hides in the .env blocks and code snippets, not only in description tables. Diff every snippet's imports, signatures, and defaults against source.
3. License is Apache-2.0. The repository LICENSE and all 15 package.json files use Apache-2.0. Never write MIT.
4. Node.js floors. The published consumer floor is >=22.13.0. Examples that run TypeScript sources directly (node src/index.ts, native type stripping) require >=25.2.0 — state the higher floor only where it is actually needed and say why.
5. Interceptor chain order follows ADR-024. The fixed default chain is errorHandler → timeout → bulkhead → circuitBreaker → retry → fallback → validation → serializer; only errorHandler and validation are enabled by default, resilience is opt-in. Auth/authz interceptors go immediately after errorHandler, before resilience and validation. Code samples and chain diagrams must agree with each other and with ADR-024.
6. Generated-code import extensions. #gen/* import extensions follow the project's buf.gen.yaml import_extension. Connectum example/consumer projects run TypeScript directly, so they generate and import .ts (import_extension=.ts + allowImportingTsExtensions: true); compiled packages use .js. Show .ts in consumer-facing examples to match the flagship examples (getting-started, hris, car-sharing).
7. Prefer the generated API Reference over exhaustive hand-written export tables. Document the load-bearing surface and link to /en/api/ for the complete list.
8. When the docs disagree with the source, the source wins — fix the docs. When two docs disagree and no source settles it, escalate rather than pick a favorite.

See also

• CLI Commands
• Development Setup
• ADR Index