Documentation Standards

This page defines how we write and maintain documentation across the monorepo. It applies to both the frontend (apps/web) and backend (apps/functions) and follows industry-standard documentation practices (Diátaxis, API reference conventions, and accessible, example-driven guides).

Goals

• Clarity: Write for the intended audience and task.
• Consistency: Use consistent structure, terminology, and formatting.
• Completeness: Include purpose, inputs, outputs, edge cases, examples, and links to source.
• Maintainability: Keep docs close to code; update in the same PR as code changes.

Document Types (Diátaxis)

• Tutorials: Beginner-friendly, step-by-step walkthroughs that teach by building something end-to-end.
• How‑to guides: Task-oriented instructions to accomplish a specific goal; assume some context.
• Explanations: Conceptual background, tradeoffs, ADRs, and rationale.
• Reference: Exact, authoritative specs (APIs, CLI flags, schemas, props).

Each new doc should identify its type in the opening paragraph.

File Conventions

• Location: Place pages under apps/docs/docs/ in a logical folder. Prefer grouping by domain (apps/web, apps/functions, data-model, operations).
• File names: kebab-case.md matching the final segment of the doc id.
• Frontmatter:
  • id: stable id used in links and sidebar (e.g., apps/functions/endpoints/createPost).
  • title: human-readable page title.
  • slug (optional): only when you must override the generated path.
• Links: Use relative links (e.g., ../operations/deployment) and backticks for file and symbol names.
• Media: Store images under apps/docs/static/ and reference with relative paths. Prefer Mermaid diagrams over static images when possible.

Formatting & Style

• Headings: Start sections with ## and subsections with ###. Keep sections short and scannable.
• Voice: Present tense, active voice, and imperative for steps ("Run", "Open"). Avoid filler ("simply", "obviously").
• Terminology: Use consistent terms for core concepts. Define acronyms on first use.
• Code:
  • Always include a language tag (js, ts, bash, json).
  • Prefer small, runnable snippets. Show input, output, and error examples.
  • Wrap lines at a reasonable width; avoid horizontal scrolling.
  • For API or schema examples, show both request and response (success and error).
• Admonitions: Use :::note, :::tip, :::warning, :::caution for important context.
• Tables: Use for parameters, props, and status codes when they improve scannability.
• Accessibility: Provide alt text for images; ensure diagrams are described in nearby text.

Cross‑cutting Requirements

• Source references: Link to the implementation file (e.g., apps/functions/createPost.js).
• Versioning: Document breaking changes explicitly. When an endpoint or prop changes, note the version and migration path.
• Changelogs: Summarize notable documentation changes in PR descriptions; link affected pages.
• Testing: If adding examples, verify they compile/run where feasible. Keep examples in sync with exported APIs.

Frontend Documentation (apps/web)

Components

Each component page should include:

• Purpose: What problem the component solves; when to use it.
• Props: A table with name, type, required?, default, description, and examples.
• Usage: Minimal examples and one complete example showing composition.
• Accessibility: Keyboard interaction, ARIA roles, focus management.
• States: Loading, empty, error, disabled; and how to represent them.
• Performance: Memoization and render-cost notes when relevant.
• Styling: We use react-bootstrap components and avoid unnecessary wrappers; keep custom styles minimal and colocated.

Example props table:

| Prop            | Type                | Required | Default | Description                          |
|-----------------|---------------------|----------|---------|--------------------------------------|
| companyId       | string              | yes      | —       | Company identifier to fetch posts.   |
| initialPage     | number              | no       | 1       | Initial page index for pagination.   |
| onPostSelected  | (post) => void      | no       | —       | Callback when a post is selected.    |

Hooks

Include signature, parameters, return shape, cache/side-effects, and examples.

// Signature
function useCompanyPosts(companyId: string, options?: { page?: number }): {
  isLoading: boolean;
  error?: Error;
  data?: CompanyPost[];
  refresh: () => Promise<void>;
}

Pages & Routes

For each route document:

• Path: e.g., /posts/[id].
• Auth: Protected/public; required claims/roles.
• Data sources: Queries, subscriptions, and cache strategy.
• Loading states: Skeletons/spinners and empty states.
• Side effects: Analytics, webhooks, or cache invalidations.

Backend Documentation (apps/functions)

Endpoint Reference Format

Each endpoint page must include:

• Method & Path: e.g., POST /createPost.
• Auth: Required headers/claims and error codes for auth failures.
• Request: Body schema with field types and requirements; example payloads.
• Responses: All status codes with example bodies; include error shapes.
• Side effects: Data writes, external calls, idempotency guarantees.
• Rate limits: If applicable, limits and headers.
• Source: Link to implementation file.

Example request/response blocks:

Request:

{
  "businessId": "biz_123",
  "participantId": "par_789",
  "title": "Post title",
  "content": "..."
}

201 Created:

{ "success": true, "id": "post_456", "data": {} }

400 Bad Request:

{ "error": { "code": "invalid_request", "message": "title is required" } }

Functions, Triggers, and Jobs

For non-HTTP functions, document:

• Trigger: Event type, path/pattern, and filter conditions.
• Input/Output: Event payload shape and side effects.
• Reliability: Retries, timeouts, idempotency, and dead-letter handling.
• Observability: Logs, metrics, and alerting.

Data Model

When documenting collections/documents:

• Schema: Field names, types, optional/required, and invariants.
• Indexes: Required composite indexes with console links.
• Security rules: Link to apps/docs/docs/operations/firestore-rules.md and call out key constraints.
• Migrations: Describe backfills and rollout/rollback plans for schema changes.

Diagrams

Prefer Mermaid for sequence, flow, and entity diagrams. Co-locate diagram source within the page so it stays up-to-date.

sequenceDiagram
  participant Web as Web App
  participant API as Cloud Functions
  participant DB as Firestore
  Web->>API: POST /createPost
  API->>DB: write post
  API-->>Web: 201 Created

Templates

Endpoint Template

---
title: METHOD /path
---

- Auth: ...
- Request: ... (schema + example)
- Responses: ... (200/201/4xx/5xx with examples)
- Side effects: ...
- Rate limits: ...

Source: `apps/functions/<file>.js`.

Component Template

---
title: <ComponentName>
---

Purpose: ...

Props:

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

Usage: `<ComponentName />`

Accessibility: ...

Hook Template

---
title: useThing
---

Signature: `function useThing(arg: string): { data?: T; isLoading: boolean; error?: Error }`

Parameters: ...
Returns: ...
Examples: ...

Review Checklist

• Accurate: Matches current code and validated examples.
• Complete: Covers purpose, parameters, edge cases, errors, and examples.
• Consistent: Follows structure and style rules above.
• Navigable: Linked from the appropriate sidebar category.
• Tested: Snippets are runnable or compile where feasible.