Skip to content

Documenting things

A feature without a doc page is incomplete.

The rule

When you add or meaningfully change something that affects:

  • A model field
  • A view's behaviour
  • A URL route
  • A form's accepted shape
  • A toggle, button, or filter in the UI
  • A setting or env var
  • A Makefile target or systemd service

…you also update the docs. Same PR. Not "I'll do it later."

Where things live

Change Doc page
New model docs/models/<model>.md (new)
Field added to existing model docs/models/<model>.md (edit)
New view + URL docs/reference/url-routes.md (edit) + a feature page if it's user-facing
New user-facing feature docs/features/<feature>.md (new)
Design decision docs/design-<topic>.md draft, linked from docs/design/drafts.md
Settings / env vars docs/reference/settings.md (edit)
Makefile / services docs/reference/makefile.md (edit)
Architectural shift docs/architecture/ (edit existing or new page)

Style

  • Lead with the result. What does this do, in one sentence?
  • Show the request lifecycle / data flow if there's one. ASCII boxes beat prose.
  • Tables for fields, choices, constraints. Easy to scan; easy to keep up to date.
  • Code blocks only for things you actually want copy-pasted (snippets, env vars, urls).
  • Link inwards aggressively. A doc page that explains a concept once and links to it from three others beats restating the concept.

Format

Each page starts with a Lucide icon frontmatter:

---
icon: lucide/<icon-name>
---

# Page title

One-sentence summary.

Then sections. Keep them shallow — #, ##, occasionally ###. Two-deep is plenty for technical reference.

Admonitions

!!! info "Phase 2"
    The tenant switcher UI lands with Phase 2. Until then there's no UI to
    switch — the session storage hook exists in `_get_active_tenant`.

Common admonition types: info, note, tip, warning, danger, example.

Linking

Use relative paths to other docs:

See [Tenant + VRF](../architecture/tenant-vrf.md) for details.

Section anchors are auto-generated:

See [the uniqueness trick](../architecture/tenant-vrf.md#the-uniqueness-trick).

Local preview

make docs-up        # http://localhost:8001
make docs-logs      # tail

The dev server hot-reloads on .md change. Nav changes (adding pages to zensical.toml) need a manual make docs-restart.

Building for prod

.venv/bin/zensical build

Writes static HTML to site/. Deploy that anywhere.

Why we do this

Docs that are part of the build, not a wiki, three things follow:

  1. They live next to the code they describe — diffs travel together
  2. They're discoverable (one URL, one nav, one search box)
  3. They rot less — you trip over a wrong sentence while editing the page you just changed

The best-documented platforms do this. We do this.