docs(rwm): trim trade-off prose, align diagram with dj.Diagram, restructure concrete-first#186
Open
dimitri-yatsenko wants to merge 4 commits into
Open
docs(rwm): trim trade-off prose, align diagram with dj.Diagram, restructure concrete-first#186dimitri-yatsenko wants to merge 4 commits into
dimitri-yatsenko wants to merge 4 commits into
Conversation
Placeholder for follow-up work after #184 (expand RWM) and #185 (deeper concept pages) merge. Tracker file outlines what to trim, why, and how to pick the work up once both upstream PRs land. No content changes to docs source in this PR. The tracker file is to be deleted in the same commit that applies the trim.
The developed argument lives on the Comparison to Workflow Languages page (added in #185). The RWM page now mentions the trade-off in one paragraph and links out, preventing drift between two homes for the same argument. Removes the .github/follow-ups/ tracker that scheduled this work.
dimitri-yatsenko
force-pushed
the
wip/trim-rwm-deliberate-tradeoff
branch
from
c60ffe6 to
cbb578f
Compare
dimitri-yatsenko
changed the title
Match the conventions from datajoint-python's dj.Diagram (diagram.py:1017-1082): - Manual: green rectangle (unchanged) - Lookup: plaintext — no border/fill (was a filled rectangle) - Imported: blue stadium-shaped node — closest Mermaid approximation to dj.Diagram's ellipse - Computed: red stadium-shaped node — same Drop the inline tier-name and make() annotations on each node; tier is now conveyed by shape and color alone, as in the real diagrams. A new lead paragraph spells out the convention so the reader can decode the diagram without a separate legend.
dimitri-yatsenko
changed the title
Two structural cleanups on relational-workflow-model.md:
Concrete-first ordering. Open with a tight paragraph naming the
model, then lead with the worked example (diagram + walkthrough).
The historical lineage (Codd/Chen/RWM three interpretations) now
follows the example, placing DataJoint's contribution in context
once the reader has a concrete pipeline to anchor on. The closing
side-by-side reading table moves to the end of the page.
Reframe as interpretation, not departure. Classical relational
concepts (tables, rows, foreign keys, normalization, the query
algebra) apply unchanged; RWM adds a semantic interpretation on
top. Renamed and rewrote two sections to reflect this:
- "Four shifts from the classical relational model"
→ "A semantic interpretation, not a departure"
Bullets now read additively ("tables also represent workflow
steps") rather than contrastively ("not merely categories").
- "From transactions to transformations"
→ "Two readings of the same schema"
Lead-in clarifies both readings hold simultaneously. Column
header changes from "Traditional view" to "Classical reading."
dimitri-yatsenko
changed the title
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
1 participant
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.
Summary
Three cleanups on
src/explanation/relational-workflow-model.md:Trim the "deliberate trade-off" subsection. After Expand Relational Workflow Model concept page #184 (expanded RWM intro) and Add two deeper concept pages: Schema as a Workflow Specification + Comparison to Workflow Languages #185 (new Comparison to Workflow Languages page), the same argument lived in two places. Now: one-paragraph mention on the RWM page that links out to the developed treatment on the Comparison page.
Align the worked-example diagram with
dj.Diagramnotation. The Mermaid in the page now matches the actual conventions fromdatajoint-python/src/datajoint/diagram.py:1017-1082:ellipse)make()annotations on each node removed; tier is conveyed by shape + color, as in realdj.Diagramoutput.Restructure concrete-first and reframe as added interpretation, not shift.
Also removes the
.github/follow-ups/trim-rwm-deliberate-tradeoff.mdtracker that scheduled the first cleanup.Test plan
mkdocs build --strictsucceeds (no new broken links/anchors)mkdocs serve