Expand Relational Workflow Model concept page#184
Open
dimitri-yatsenko wants to merge 1 commit into
Open
Conversation
The previous intro understated the model's significance. The expansion positions the RWM for an informatics-knowledgeable reader: - Lead with the three-interpretations taxonomy (Codd / Chen / RWM) and the computational-substrate framing from the DataJoint 2.0 preprint. - Name the surrounding tool categories explicitly (CWL/Snakemake/Nextflow, Airflow/Argo/Prefect, DataHub/Atlan/Marquez, Delta/Iceberg/Hudi) and what each is silent on. - Add a worked example pipeline (Mouse > Session > Scan > AverageFrame > Segmentation > Fluorescence, with SegmentationParam as Lookup) rendered as a mermaid diagram with tier colors. - Add a "deliberate trade-off" section addressing the legitimate strengths of decoupled architectures and why DataJoint accepts coupling. - Add a substrate-consequences section: provenance and lineage as structural properties (mapping to W3C PROV / OpenLineage is translation, not reconstruction), and the five agent-substrate properties (self-describing, safe by default, explicit dependencies, idempotent, observable) from the preprint. - Preserve the existing detailed sections (table tiers, master-part, normalization, entity integrity, query algebra, transactions vs transformations) under a "Beneath the model" header for readers who want the structural detail.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
The current Relational Workflow Model (RWM) concept page (
src/explanation/relational-workflow-model.md) is understated relative to the model's significance. It reads as a brief positioning statement rather than as an entry point that lands the structural argument for a reader who already knows informatics (databases, FK graphs, ER modeling, workflow managers, lakehouses).This PR expands the page to function as that entry point — the audience pictured is a knowledgeable peer (e.g., an infrastructure architect from pharma R&D evaluating where DataJoint sits in the landscape they already know).
Changes
Net change
+177 / -112lines; one file.Sources
Notes for reviewers
classDefs. If the docs site's mermaid theme overrides these, we may need to drop colors or adapt to the site theme.src/explanation/andsrc/how-to/content.