Skip to main content

Documentation Standards

This document defines how we write and maintain docs for the project. It applies to guides, references, API docs, architectural docs, runbooks, and in-repo docs across frontend and backend.

Principles​

  • Audience-first: Explain why before how; assume smart readers who don’t know our system.
  • Clarity over cleverness: Prefer simple, direct language. Avoid internal jargon.
  • Consistency: Follow the formats below so readers know what to expect.
  • Accuracy: Code and responses shown must be runnable or clearly marked as illustrative.
  • Maintainability: Co-locate docs with code ownership; keep short, modular pages.

Page Types and Structure​

Use the appropriate template, in this order of preference.

  • How-to Guide (Task-focused)

    • Frontmatter: title, description (one-sentence outcome), optional tags.
    • Sections: Prerequisites → Steps (ordered) → Verification → Troubleshooting → Next steps.
    • Style: Imperative mood ("Run", "Open", "Click").

  • Concept (Explainer)

    • Explain the why, trade-offs, and mental models. Avoid step-by-step instructions.
    • Sections: Overview → Key Concepts → Examples → Related.

  • Reference (Exact, exhaustive)

    • Tables for fields, types, defaults, constraints, and examples.
    • Keep normative language (MUST/SHOULD/MAY) precise.

  • Runbook (Operations)

    • Audience: on-call engineers. Include severity, detection, dashboards, commands, and rollback.

  • Decision Record (ADR)

    • Context → Decision → Consequences → Alternatives. Link PRs and issues.

Writing Style​

  • Use active voice, present tense, second person. Example: "Run pnpm dev".
  • Keep sentences short (≤ 25 words). Prefer lists over long paragraphs.
  • Use internationally friendly formats: ISO 8601 for dates; UTC for times; SI units.
  • Use inclusive, respectful language. Avoid idioms and culture-specific references.
  • Prefer American English spelling for consistency (e.g., "behavior").

Formatting Conventions​

  • Headings: Start with ## under the title; avoid skipping levels.
  • Code blocks: Use language tags and minimal, copy-pasteable snippets.
    • Show both shell and JavaScript/TypeScript if relevant.
    • Use placeholders like <PROJECT_ID> and document how to obtain values.
  • Inline code for identifiers and filenames (e.g., apps/web/src/app/page.js).
  • Admonitions for important context:
    • :::tip for shortcuts, :::note for context, :::warning for risky steps.
  • Diagrams: Prefer React Flow components (MermaidToReactFlow) for architecture and flows; keep them near the text they explain.
  • Images: Add alt text; compress and place under apps/docs/static/img/.

File Organization​

  • Place docs under the closest relevant area (e.g., docs/development/…, docs/apis/…).
  • Filenames: kebab-case.md. Keep IDs implicit via path; avoid custom id unless necessary.
  • Cross-link using relative doc IDs (e.g., [Billing Webhooks](apis/web-api#webhooks)).
  • Avoid very long pages; split when sections exceed ~7 minutes read time.

Frontend Documentation Standards​

  • Components
    • Document purpose, usage example, and constraints.
    • Include a props table with name, type, default, required, and description.
    • Cover accessibility: keyboard behavior, ARIA attributes, focus management, and color contrast.
    • Note performance considerations: memoization, virtualization, lazy loading.
    • Example structure:
### Usage

```tsx
<Sidebar collapsed defaultOpen>
  …
</Sidebar>
```

### Props

| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
| `collapsed` | `boolean` | `false` | no | Starts the sidebar collapsed. |

  • Pages and Routes (Next.js)

    • Document route path, data sources, loading behavior, error handling, and auth requirements.
    • Note whether a route uses Server Components, route.js handlers, or middleware.
    • Include any environment variables consumed in the client.

  • Styling and Design Tokens

    • Reference Tailwind classes and any design tokens. Document responsive behavior and theming.

Backend Documentation Standards​

  • API Endpoints (HTTP)

    • For each endpoint: method, path, auth, query/path params, request body, response schema, status codes, pagination, rate limits, and idempotency guidance.
    • Provide examples in curl and fetch/axios with realistic payloads.
    • Keep a canonical schema (OpenAPI/JSON Schema) and link to it if available.

  • Background Jobs and Functions

    • Triggers, schedules, retries, timeouts, and failure handling.
    • Inputs/outputs, side effects, permissions, and observability (logs, metrics, traces).
    • Environment variables and secrets required.

  • Data and Security

    • Firestore collections, indexes, and reference patterns; include sample documents.
    • Access controls: rules, roles, and validations; link to security/security where relevant.
    • Migration steps and backward compatibility expectations.

Code Example Standards​

  • Prefer TypeScript types when available; include minimal but complete examples.
  • Wrap long lines; avoid secrets; use .env placeholders (NEXT_PUBLIC_… vs server-only).
  • Label partial snippets with ellipses or comments to indicate omissions.
  • Validate examples against linters/formatters used in the repo.

Versioning and Changelogs​

  • Update docs with any breaking or behavior changes in the same PR as the code.
  • Maintain a concise changelog section per page when stability matters.
  • Link related ADRs and PRs.

Review and Contribution Process​

  • Open a PR with the doc changes; request review from code owners for impacted areas.
  • Checklists before merging:
    • Links resolve; no TODOs left; examples run or are clearly marked.
    • Consistent headings, terminology, and code style.
    • Images optimized and have alt text; diagrams render correctly.

Templates​

Copy these inline into new pages and customize.

How-to Template​

---
title: <Actionable Title>
description: One-sentence outcome.
---

## Prerequisites

- …

## Steps

1. …

## Verify

- …

## Troubleshooting

- …

## Next steps

- …

API Endpoint Template​

#### <METHOD> <PATH>

**Auth**: …  |  **Rate limit**: …  |  **Idempotency**: …

Request

```json
{
  "…": "…"
}
```

Response

```json
{
  "…": "…"
}
```

Errors

| Code | Message | When |
|---|---|---|
| 400 | invalid_… | … |

Component Template​

## <ComponentName>

Purpose: …

### Usage

```tsx
<ComponentName propA="…" />
```

### Props

| Prop | Type | Default | Required | Description |
|---|---|---|---|---|
| … | … | … | … | … |