Repository navigation
Docs: represent the DataJoint book's core principles (coverage review) #225
Copy link
Copy link
Closed
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Description
Umbrella tracking a book → docs coverage review: an audit of the core principles taught in the DataJoint book against the published documentation. Across ~37 principles in three clusters (integrity/keys, normalization, computation/reproducibility), the docs are solid overall — and stronger than the book on the make() reproducibility contract — with the gaps below.
New pages / major expansions
- Add an integrity-types explanation page (the seven integrity types) #217 — Integrity-types explanation page (the seven integrity types + rules→constraints map)
- Add a referential-integrity / foreign-keys explanation page #218 — Referential-integrity / foreign-keys explanation page (FK = runtime logical constraint, not a pointer; the five effects incl. auto-index)
- Expand normalization.md to the book's three-lens treatment #219 — Expand
normalization.mdto the three-lens treatment (+ the Order example that shows workflow normalization is stricter than 3NF) - Add a Transactions / ACID explanation page #220 — Transactions / ACID explanation page
Targeted additions & one fix
- insert-data how-to: add insertion-discipline / reproducibility guardrails #221 —
insert-datahow-to: insertion-discipline / reproducibility guardrails (in progress) - master-part spec: state that a dependency on the master implies its parts #222 — master-part spec: "a dependency on the master implies dependency on all its parts"
- Add an 'update data' how-to #223 — An "update data" how-to (updates are rare; delete + reinsert + recompute)
- Fix contradiction: autopopulate.md §5.5 shows a transaction inside make() #224 — Fix:
autopopulate.md§5.5 shows a transaction insidemake(), contradictingcomputation-model.md
Already addressed while this review ran
The audit baselined main, so these showed as gaps there but are closed on in-flight branches:
- "Referential integrity is impossible without entity integrity" →
entity-integrity.md(docs: interlink schema-design concepts; fix PK/entity-integrity examples #216) - Natural-key "real-world use" test in the how-to →
design-primary-keys.md(docs: interlink schema-design concepts; fix PK/entity-integrity examples #216) - Concept interlinking (normalization was a link-island; PK ↔ entity-integrity mutual) (docs: interlink schema-design concepts; fix PK/entity-integrity examples #216)
- Primary-key guideline corrections — dropped the fixed-width "joins faster" myth, "avoid dates", "avoid computed values"; added the floating-point-key warning (docs: interlink schema-design concepts; fix PK/entity-integrity examples #216)
- Delete → garbage-collection lifecycle link →
delete-data.md
Where the docs already win (no action)
The make() reproducibility contract (formalized beyond the book), no-auto-increment rationale, the three questions of entity integrity, schema dimensions & lineage, cardinality-from-FK-placement, tripartite make(), and the mouse/cage normalization example.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Activity
dimitri-yatsenko commentedon Jul 18, 2026
Progress — PRs opened for all of P1–P8:
All three PRs are drafts pending review on the docs server. Separately, #205 (executed tripartite-
make()worked example) is in progress.dimitri-yatsenko commentedon Jul 21, 2026
All tracked items from this coverage review are now resolved:
Closing the umbrella.