Skip to content

docs(ep3): correct the reflection claim and unknot the slide copy - #200

Merged
simontaurus merged 1 commit into
mainfrom
docs/ep3-copy-clarity
Oct 8, 2026
Merged

simontaurus merged 1 commit into
mainfrom
docs/ep3-copy-clarity

Conversation

@simontaurus

Copy link
Copy Markdown
Contributor

On-screen copy for tutorial episode 3. One correctness fix, the rest readability.

Wrong since rc.5

This implies that all occurrences of $ref in the schema are reflected in the JSON-LD context.

#187 scoped OOLD-CMP-b926 to $ref whose target is itself an OO-LD schema; a $ref to a plain JSON Schema carries no terms and reflects nothing. The slide and the closing recap both still taught the unscoped claim.

Slide 7

  • Organization does both at once: an extension at the root, **which is the next move**, and an embedded object under the address property. The forward reference splits the pair the sentence is introducing, so the reader loses which two things are meant. Dropped rather than relocated: the next scene is "is a", so the tease earns nothing.
  • **Whether** the value is one object **or** the items of an array, the reference is reflected as a scoped @context on the term. A fronted concessive clause before the point. Now One object, or an array of them: either way the reference becomes a scoped @context on that term.

Five more

  • B in allOf at the root and p0, which is not object-valued, **are listed**... put a relative clause between a compound subject and its verb
  • allOf is conjunctive, so additionalProperties never sees the members the other branches contribute **and rejects them** reads as a contradiction on first pass
  • It takes x-oold-range, the keyword from episode 2, **instead of a $ref** split "takes X instead of Y" across an appositive
  • later entries **override** earlier ones, so a schema **overrides** an inherited term used one verb for two actors
  • scoped inline instead, **where** they cannot collide at the root dangled the relative

Seven of nine strings got shorter. The two that grew sit in wrapping containers alongside longer siblings (exampleNote2 is 190 chars in the same block), so no reflow. The render diff on this PR covers the affected beats.

@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

tutorials beats changed by this pull request

ep3-dark - 8 changed

07-hasa-organization (before | after)

07-hasa-organization

09-isa-person-allof (before | after)

09-isa-person-allof

13-reflect-rule (before | after)

13-reflect-rule

15-reflect-example (before | after)

15-reflect-example

17-reflect-merge (before | after)

17-reflect-merge

18-closing-problem (before | after)

18-closing-problem

19-closing-unevaluated (before | after)

19-closing-unevaluated

21-recap (before | after)

21-recap

ep3-light - 8 changed

07-hasa-organization (before | after)

07-hasa-organization

09-isa-person-allof (before | after)

09-isa-person-allof

13-reflect-rule (before | after)

13-reflect-rule

15-reflect-example (before | after)

15-reflect-example

17-reflect-merge (before | after)

17-reflect-merge

18-closing-problem (before | after)

18-closing-problem

19-closing-unevaluated (before | after)

19-closing-unevaluated

21-recap (before | after)

21-recap

Rendered from 9ccaa287a57432a7e761622d4113665270b5285d. Left is the merge base, right is this pull request. Images live on the ci-review-images prerelease, not in the repository.

- the narration said every $ref is reflected into the @context; rc.5
  scoped OOLD-CMP-b926 to refs whose target is an OO-LD schema
- slide 7 interrupted 'both at once: A and B' with a forward reference
  to the next scene, and opened the following note on a concessive
  clause
- five more sentences reordered so the verb follows its subject
@simontaurus
simontaurus force-pushed the docs/ep3-copy-clarity branch from 02e62bc to 1d65818 Compare October 8, 2026 05:00
@simontaurus
simontaurus merged commit 9553012 into main Oct 8, 2026
14 checks passed
@simontaurus
simontaurus deleted the docs/ep3-copy-clarity branch October 8, 2026 05:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant