Feature Docs Template
Feature Docs Template
Every feature in Guides follows the same ten sections, in the same order. A developer learns the shape once and finds it everywhere. Messaging is the reference implementation — copy it.
The template
| # | Section (section: slug) | What it answers |
|---|---|---|
| 1 | Overview (overview) | What is it, when to use it, key concepts, capability matrix |
| 2 | Architecture (architecture) | How it works: request/inbound flow, building blocks, dependency direction |
| 3 | Frontend Integration (frontend-integration) | For web/mobile devs: permissions, endpoint sequence, realtime, UI concerns |
| 4 | Backend Integration (backend-integration) | For backend devs: services, controllers, permissions, DB, events, queues |
| 5 | REST API (rest-api) | The endpoint tables + request shapes, linking into the API reference |
| 6 | Events (events) | Realtime (WebSocket) + internal domain events, with payloads |
| 7 | Webhooks (webhooks) | Inbound/outbound webhooks, signature verification |
| 8 | Examples (examples) | Copy-paste requests in cURL / JS / Node |
| 9 | Troubleshooting (troubleshooting) | The common failures and the one-line fix |
| 10 | Best Practices (best-practices) | The recommended way to build, ✓ / ✗ |
Not every feature needs all ten (a feature with no webhooks skips section 7) — but keep the order and names identical so navigation is muscle memory.
How to add a feature's docs
- Co-locate the Markdown with the module (e.g.
src/api/v1/<module>/docs/*.md). - Add frontmatter to each page:
--- publish: true doc_type: guide feature: messaging # crm | messaging | automation | ai | billing | integrations section: frontend-integration --- - Run
npm run docs:guides(ornpm run docs:serve). The page appears under Guides › <Feature> › <Section>, ordered by the template automatically.
The section order and labels are defined in scripts/sync-guides.ts (SECTIONS);
features and their order in FEATURES.
Definition of done
A feature ships with, at minimum: Overview → one integration page (frontend or backend) → REST API. Everything else is filled in as the feature matures. Docs land in the same change as the feature — never as a follow-up.
Beyond Guides
- Implementation Guides — end-to-end "Build a …"
walkthroughs that combine several features (
doc_type: implementation). - Recipes — 5–10 minute single tasks (
doc_type: recipe). - Get Started — Quickstart, Data Model, Errors (
doc_type: get-started). - Engineering — architecture, isolation, authorization, internal specs (
doc_type: engineering).