Skip to content

Editions & structure

A title is rarely one thing. Hands-On Machine Learning with Go is an English text, a Spanish translation, an audiobook, and perhaps a video course built from the same material. Each of those is an Expression of the one Work: the Work in one medium and one language.

This page explains what an Expression is made of, how editions of the same Work share a structure so that "Chapter 3" means the same thing in each, and what happens when an edition has a shape of its own.

The model in one line

A Resource is content, a ContentUnit names a part, and an Expression is an ordered list of Resources in which each one can say which part it is.

Three things a Work has

Thing Question it answers Example
Resource What content does the Work hold? Chapter 3 as a document; its Spanish translation
ContentUnit What are the Work's parts, by name? Part I › Chapter 3
Expression Which Resources make up one edition? "Spanish text": twelve chapters, in reading order

An Expression lists whole Resources in reading order. Each entry is a part. A part either follows its Resource's latest content or is held at a snapshot version, so a published edition does not move while its chapters are still being edited.

One structure, many editions

A structure is a tree of ContentUnits: the book, its parts, its chapters. Every Expression follows one. Each part of the Expression can then be bound to the unit it realises — this Resource is Chapter 3 of this edition.

flowchart TD
    subgraph ST["Structure · the book"]
        S["Book"] --> P1["Part I"]
        P1 --> C3["Chapter 3"]
        P1 --> C4["Chapter 4"]
    end
    subgraph EN["Expression · English text"]
        EN3["Chapter 3 document"]
        EN4["Chapter 4 document"]
    end
    subgraph ES["Expression · Spanish text"]
        ES3["Capítulo 3 document"]
        ES4["Capítulo 4 document"]
    end
    subgraph AU["Expression · English audio"]
        AU3["Chapter 3 narration"]
    end
    EN3 -->|is| C3
    ES3 -->|is| C3
    AU3 -->|is| C3
    EN4 -->|is| C4
    ES4 -->|is| C4

The English chapter, the Spanish chapter and the narration are three different Resources in three Expressions. They are bound to the same unit, which makes them counterparts: the same chapter, three ways. That is what lets a reader switch language mid-chapter, an editor see that the Spanish Chapter 4 exists but its narration does not, and a pipeline know which translated chapter is out of date when the English one changes.

A unit carries no language and no medium. It is only the name of the part, with a stable ID (cu_…), which is why every edition can share it.

When an edition has its own shape

Not every edition has the book's chapters. A video course made from the book is organised into modules and lessons, and there is no "Chapter 3" in it. So a Work can hold more than one structure, and each Expression follows the one that fits.

When an Expression is derived from another, the platform picks a sensible default from the kind of derivation:

flowchart LR
    SRC["Source edition<br/>follows the book's structure"]
    SRC --> T["Translation"]
    SRC --> A["Audiobook"]
    SRC --> M["Another format"]
    SRC --> E["Revised edition"]
    SRC --> PE["Persona edition"]
    SRC --> TR["Transcript"]
    SRC --> AD["Adaptation<br/>e.g. video course"]
    SRC --> CO["Compilation"]
    SRC --> SU["Summary"]
    SRC --> AS["Assessment"]
    T --> SAME(["shares the source's structure"])
    A --> SAME
    M --> SAME
    E --> SAME
    PE --> SAME
    TR --> SAME
    AD --> OWN(["starts a structure of its own"])
    CO --> OWN
    SU --> OWN
    AS --> OWN
  • Faithful editions share. A translation, a narration, another format, a revised or persona edition and a transcript keep the source's chapters, so they follow the same structure and their parts line up with the source's automatically.
  • Reshaped editions start fresh. An adaptation, a compilation, a summary and an assessment are organised by their own medium, so each starts a structure of its own.

The default can always be overridden: an abridged audiobook that drops chapters can be given its own structure.

An edition with its own structure is not cut off from where it came from. Its origin still names the edition it was derived from, and the Activity that produced each piece records exactly what it used. Structure says what the parts are; provenance says where they came from.

A persona edition is a whole-book edition

An edition rewritten for a particular reader — the book for site reliability engineers, say — is a full Expression of its own with newly written chapters. Because it keeps the book's chapters, it shares the book's structure, and each rewritten chapter is the counterpart of the one it came from.

The rules

A handful of rules keep the model honest.

flowchart TD
    A["Bind a part to a unit"] --> B{"Is the unit in this<br/>Expression's structure?"}
    B -- no --> X1["Refused"]
    B -- yes --> C{"Can a whole Resource<br/>be that unit?"}
    C -- "no — it names another Resource,<br/>or only a span of one" --> X1
    C -- yes --> D{"Is another part of this<br/>Expression already that unit?"}
    D -- yes --> X2["Refused<br/>one answer per edition"]
    D -- no --> OK["Bound"]
Rule Why
Every part is a Resource of the Expression's own Work. Rights and revenue are accounted per Work. A collection holds its own copies of what it gathers.
A structure and its units belong to one Work. Borrowing across Works needs recorded consent and a royalty share, which is not modelled yet.
A part binds only to a unit of the structure its Expression follows. A course lesson is not a chapter of the book.
At most one part of an Expression per unit. "Chapter 3 of this edition" has exactly one answer.
An Expression cannot change structure while parts are bound. The bindings would point at units outside the new structure.
A unit with units beneath it cannot be deleted. Remove the leaves first.
A unit an Expression follows or binds cannot be deleted. The edition would point at something that is gone.
A unit an Activity names is never deleted. The Activity may have generated royalty entitlements, and that record must keep resolving.

Binding is optional. An edition can be assembled first — Resources in order — and bound to units later, or never, if nothing needs to line it up with another edition.

What this makes possible

  • The same chapter everywhere. Ask for a chapter's counterparts and get it in every language and medium the Work has.
  • Honest progress. A translation of a twelve-chapter book shows which of the twelve exist, by name, not just a count.
  • Staleness you can see. A translated part records the version of the source it was made from; when the source moves on, the part is flagged as stale.
  • A real table of contents. An edition's outline shows each part under the units that contain it — Part I › Chapter 3 — alongside the headings inside it.
  • Works & rights — the Work every Expression realises, and where its rights are held.
  • Resources & versions — the content an Expression is made of, and the snapshot versions parts are held at.
  • Provenance & attribution — how a derived edition stays tied to what it was made from.
  • Core concepts — the Work → Expression → Manifestation → Product ladder in one place.