Domain documentation strategy (DocType reference)

Purpose

The site includes 200+ generated pages under DocType reference. Many follow the same structure: overview, source paths, placeholder narrative, field table. Filling every page to hundreds of lines of English analysis is not maintainable without prioritization.

This page defines the agreed strategy (see ADR-004) for:

1. Generated pages — keep accurate field tables and links to source.
2. Overlays — curated notes in docs/doctype-overlays/overlays.json (or equivalent) consumed by the generator.
3. Domain deep dives — one narrative per business domain (e.g. incorporation, finance AR, payroll) under Modules or ER diagrams by domain, linking clusters of DocTypes.

Tiers of documentation

Tier	Audience	Content	Typical length
D1 — Critical path	Engineers changing billing, payroll, compliance	Lifecycle, invariants, integration touchpoints, failure modes	300–800 lines English, split across linked pages if needed
D2 — Standard custom	Feature teams	Purpose, key links, 1–2 sequence diagrams	80–200 lines per DocType or small group
D3 — Lookup / child tables	Implementers	Field table + parent DocType link	Short generated page + domain link

Priority domains (indicative)

Use your backlog to refine; common high-impact areas in this codebase include:

• Finance & AR — Xero, Stripe, debt, invoicing — Domain deep dive — Finance & AR plus generated finance-ar-integrations.
• Incorporation & application — long-lived workflows and PDFs — Domain deep dive — Incorporation & application plus generated incorporation-application.
• Payroll & HR — Singapore-specific settings — Domain deep dive — Payroll & HR plus generated payroll-hr.
• Corporate AGM — schedulers and compliance — Domain deep dive — Corporate AGM plus generated corporate-agm.
• Automation & communications — auto-email, templates, Mandrill, DocuSign queue — Domain deep dive — Automation & communications plus generated automation-comms.
• Time tracking — isolated module and guest APIs — Domain deep dive — Time tracking plus generated time-tracking.
• Platform & admin — portal, Singpass, AI keys, cross-cutting settings — Domain deep dive — Platform & admin plus generated platform-admin.
• Accounting & compliance — statutory progress, auditing, ACRA settings, reports — Domain deep dive — Accounting & compliance plus generated accounting-compliance.
• CRM & sales support — tickets, clients, incidents, promos — Domain deep dive — CRM & sales plus generated crm-sales.

Writer workflow

1. Identify a user journey or support incident → map to DocType cluster.
2. Add or extend a domain page (English) with sequence diagrams and “what breaks if…”.
3. Add overlays for fields that confuse users or have hidden validation.
4. Avoid copying the same paragraph into 50 child DocTypes — link upward to the domain page.

Org-standard matrix (strategy vs automation)

Topic	Current state	Direction
Critical DocTypes	Long English narrative selective	Finance AR, incorporation, Xero, payroll first
Overlays	docs/doctype-overlays/overlays.json	Expand keys gradually — role + hook one-liners
Category indexes (*/index.md in doctype-reference)	Often thin	Nine data/domain-*.md deep dives exist — optional: enrich each category index.md with links to its domain page
Inventory CSV	Manual regen	Optional PR check — Documentation inventory
Sidebar	astro.config.mjs	See Feature inventory by category checklist

Related

• Domain deep dive — Finance & AR
• Domain deep dive — Incorporation & application
• Domain deep dive — Payroll & HR
• Domain deep dive — Corporate AGM
• Domain deep dive — Automation & communications
• Domain deep dive — Time tracking
• Domain deep dive — Platform & admin
• Domain deep dive — Accounting & compliance
• Domain deep dive — CRM & sales
• Documentation upgrade roadmap
• Custom DocTypes & data
• Documentation conventions
• Feature inventory by category