Skip to content

Contributing to the Documentation

docs/ is the single source of truth for dichit-backend. Documentation is part of the work — update it in the same PR as the change.

When documentation must be updated

Update docs when any of the following changes:

  • API contract — endpoints, status codes, response shapes, WS events.
  • Database schema — new/changed models, migrations, seeds.
  • Configuration — env vars, feature flags, default values.
  • Infrastructure — Redis usage, queues, caching, providers, deploy topology.
  • Workflows — scripts, CI/CD, release process, git workflow.
  • Architecture — any significant decision (record it as an ADR too).
  • Dependencies / commands — package.json scripts referenced by docs.

Rule of thumb: if a reader following the docs would now be misled, update them.

How to write documentation

  1. Copy a template, don't start blank. See templates/ — feature, REST, WS event, service, module, runbook.
  2. Write for a reader who knows code but not this feature.
  3. Prefer concrete facts over prose: commands, examples, tables, links to source files (src/...:line where useful).
  4. Keep pages focused: one topic per page, discoverable from the index in README.md.
  5. No lorem ipsum, no empty placeholders — if a section doesn't apply, drop it.

Markdown conventions

  • GitHub-flavored Markdown: ATX headings (##), tables, fenced code blocks.
  • Title is # Title (one H1 per page); sections use ##.
  • Code blocks tag the language: ```typescript, ```bash, ```json, ```prisma.
  • Emphasis is **bold** / `code`; avoid emoji and decorative styling.
  • One blank line around headings, lists, and code blocks.
  • Line width: keep lines under ~100 chars where practical.

Section order

Every page should follow the standard template where it makes sense:

# Title

## Overview

## Purpose

## Architecture

## Flow

## Examples

## Best Practices

## Related Documents

Adapt the order for pages where a section is clearly N/A.

Mermaid conventions

  • Use Mermaid for flowcharts (flowchart), sequences (sequenceDiagram), state diagrams, and ER diagrams.
  • Wrap in a fenced block with mermaid: ```mermaid
  • Keep diagrams small and legible — split big flows into several diagrams rather than one monster graph.
  • Label edges meaningfully (-->|"label"|), use subgraph for groupings, id["text"] for node labels.
  • Verify the diagram renders in GitHub before merging.
  • Style reference: architecture/diagrams.md and api/websocket/diagrams.md.

File naming conventions

  • Lowercase, kebab-case, descriptive: environment-variables.md, request-lifecycle.md.
  • ADRs: NNNN-short-slug.md under adr/ (0001-example.md).
  • Runbooks: <symptom>.md under runbooks/.
  • Templates keep their canonical names; business agreement templates live in templates/agreements/.
  • No spaces, no CamelCase file names for new docs.

Linking conventions

  • Relative links only. Never absolute /Users/... paths or full URLs to local files — they break on every other machine and in Docusaurus.
  • Navigate from a file's directory: ../database/schema.md, ./local-development.md.
  • Link to the file, not a heading, unless the heading is the stable target.
  • Prefer descriptive link text: [Redis topology](infrastructure/redis.md).
  • Every new page should be reachable from the index (README.md) and should link back to its neighbours.
  • Keep the repo Docusaurus-migration-friendly: plain relative links, no Docusaurus-only syntax, no front-matter, no custom containers.

Review checklist

Before merging documentation, confirm:

  • Content is accurate against the current code (pnpm build/runtime).
  • Template structure followed (sections in order).
  • No stale or misleading statements.
  • All relative links resolve (run the link check below).
  • Mermaid blocks render.
  • New page is added to the index in README.md.
  • Secrets/sensitive data absent.
  • File name follows naming conventions.
  • ADR added if the change is an architectural decision.

The canonical checker is scripts/docs/check_links.py (also wired into the docs CI via make docs-lint). It resolves every relative link against the real filesystem (repo root included), skips links inside code fences, and reports targets that don't exist:

.venv-docs/bin/python scripts/docs/check_links.py docs
# or, if the docs venv is ready:
make docs-check

If you prefer a no-dependency one-liner, the equivalent inline check is:

# find broken relative links across docs/ (targets that don't exist)
python3 - <<'PY'
import os, re
root = "docs"
broken = []
for dirpath, _, files in os.walk(root):
    for f in files:
        if not f.endswith(".md"):
            continue
        p = os.path.join(dirpath, f)
        text = open(p, encoding="utf-8").read()
        for m in re.finditer(r"\]\(([^)#][^)#]*?)(?:#[^)]*)?\)", text):
            t = m.group(1)
            if t.startswith(("http://", "https://", "#")):
                continue
            target = os.path.normpath(os.path.join(dirpath, t))
            if not os.path.exists(target):
                broken.append((p, t))
for p, t in broken:
    print(f"BROKEN: {p} -> {t}")
print("done" if not broken else f"{len(broken)} broken links")
PY

Reviewing someone else's docs

Apply the same checklist. Flag anything that will be wrong in three months (specific versions, undocumented assumptions), not style nitpicks.