Use of Visuals

The previous lesson established the example as the one element in a document that can test itself: an embedded claim makes noise when it goes stale. There is a second element standing beside the text, and it can never be run under any condition.

The diagram carries claims too. It claims a component’s name, a flow’s order, a field’s shape, a concept’s structure, and these claims are bound to a surface just like sentences are. This lesson’s question is: which surface is a diagram bound to, how does that choice set its rate of staleness, and why is visual staleness silent without exception?

Notation itself — what can be shown, what a notation abstracts away, what different notations of the same thing distinguish — was established in the Modeling and Representation course and is not repeated here. What is measured here is only whether a diagram serves the text: how long the claims it carries live, and who hears it when they go wrong.

A Diagram Is a Set of Claims

A diagram is not decoration; it is a set of sentences written in picture form. Three boxes and two arrows between them carry at least five claims: that three things exist, that two of them connect in a specific direction, and the order of that connection. All of these claims can be true or false; when the product changes, some part of them goes wrong.

What separates a diagram from text is not carrying claims; it is that none of the claims it carries can be run. When an example fails, it reports it; a picture never fails. The page builds, the picture stays put, the lines look as they always did, and the reader trusts them. In the previous lesson’s language: every claim moved into a diagram loses its chance of ever being embedded.

The second difference is search. When a term is renamed, a text scan cannot enter a diagram; the old name inside the picture stays outside the scan. The missed-claim problem the third lesson measured becomes unavoidable in a diagram.

These two differences also give the criterion for when a picture is worth drawing. Text is linear: sentences are read in an order, and that order is itself a claim. Narrating a sequence of steps is text’s natural job, since sequence is already the shape text takes. Relationships that all hold at once, by contrast, sequence badly in text; reading which direction three things connect in requires reading three sentences and joining them in the reader’s head. This is what a diagram buys, and the only thing it buys. A picture repeating its neighboring paragraph’s order has bought nothing and only added a maintenance debt.

The Surface a Diagram Is Bound To

Diagrams are classified not by drawing technique but by what they show, and this classification is directly a surface classification.

An interface diagram shows fields, types, and call shapes: the signature surface. A flow diagram shows the order of steps: the flow surface. A component diagram shows the parts’ names and the links between them: the name surface. A concept diagram shows why something is built the way it is — which constraint produced which decision: the concept surface.

A diagram can show more than one surface at once, and most, in practice, do. A picture like this lives as long as the fastest surface it carries: the moment a single field name inside it changes, the entire picture is no longer trustworthy, because the reader cannot tell which part of it is outdated.

The measurement’s assumptions:

• WD41 — The 56 claims come from the shared fixture: four types, four surfaces, 17 claims embedded in a runnable example. The oracle is the fixture itself.
• WD42 — The only thing this lesson adds is where a claim is carried: in text, or in a diagram. The types’ surface mix and surface frequencies do not change.
• WD43 — No claim moved into a diagram can be embedded in an example. A diagram cannot be run; no test fails when it goes stale.
• WD44 — A diagram takes over all of the claims on the surface it is bound to. This is an upper bound, and it makes the five diagram choices comparable with one another.
• WD45 — A diagram showing more than one surface goes wrong as a whole at its fastest surface’s version.
• WD46 — Two modes are measured: a replacing diagram takes claims out of the text, a duplicating diagram leaves the same claims in the text and produces one more copy of them.
• WD47 — Whether a claim is stale looks only at the surface it is bound to and the version; where it is carried does not change this, it only changes whether it is heard.

Measurement

"""Use of visuals: which surface a diagram binds to and how fast it goes stale.

Part 1 - five diagram choices: claims carried, embedded in text, first wrong version.
Part 2 - true/stale/silent when a diagram replaces text.
Part 3 - the silent claims added when a diagram duplicates text.
"""
TYPES = {
    "tutorial":      {"flow": 9, "signature": 3, "name": 2, "concept": 1},
    "how-to":        {"flow": 6, "signature": 5, "name": 2, "concept": 1},
    "explanation":   {"flow": 1, "signature": 1, "name": 1, "concept": 9},
    "reference":     {"flow": 0, "signature": 13, "name": 2, "concept": 0},
}
FREQUENCY = {"signature": 2, "flow": 3, "name": 5, "concept": 12}
EMBEDDED = {"tutorial": 0.60, "how-to": 0.70, "explanation": 0.10, "reference": 0.00}
# Every diagram is bound to one or more surfaces. A diagram cannot be run:
# no claim it carries can be embedded in an example.
DIAGRAM = {"concept diagram": ("concept",), "component diagram": ("name",),
           "flow diagram": ("flow",), "interface diagram": ("signature",),
           "mixed diagram": ("signature", "flow", "name")}


def claims():
    entries, no = [], 0
    for kind, mix in TYPES.items():
        embedded_target = 0
        for surface, count in mix.items():
            for _ in range(count):
                no += 1
                embedded_target += EMBEDDED[kind]
                embedded = embedded_target >= 1 and surface != "concept"
                if embedded:
                    embedded_target -= 1
                entries.append({"no": no, "type": kind, "surface": surface,
                                 "embedded": embedded})
    return entries


def stale(i, version):
    return version // FREQUENCY[i["surface"]] >= 1


def measure(entries, version):
    stale_ = [i for i in entries if stale(i, version)]
    silent = [i for i in stale_ if not i["embedded"]]
    return len(entries) - len(stale_), len(stale_), len(silent)


def visualize(entries, surfaces, mode):
    """A diagram can replace text or duplicate it; either way it goes silent."""
    if mode == "replacing":
        return [dict(i, embedded=i["embedded"] and i["surface"] not in surfaces)
                for i in entries]
    copy = [dict(i, embedded=False) for i in entries if i["surface"] in surfaces]
    return entries + copy


A = claims()
everything = visualize(A, tuple(FREQUENCY), "replacing")
print(f"claims {len(A)} | embedded in text {sum(i['embedded'] for i in A)} | "
      f"if all moved to diagrams, embedded {sum(i['embedded'] for i in everything)}")
print()
print(f"{'diagram':>18s} {'surface':>17s} {'claims':>6s} {'embedded in text':>17s}"
      f" {'first wrong version':>20s}")
for name, surfaces in DIAGRAM.items():
    group = [i for i in A if i["surface"] in surfaces]
    print(f"{name:>18s} {'+'.join(surfaces):>17s} {len(group):6d}"
          f" {sum(i['embedded'] for i in group):17d}"
          f" {min(FREQUENCY[y] for y in surfaces):20d}")
print()
print("when the diagram replaces text - true/stale/silent")
print(f"{'diagram':>18s} {'version 3':>12s} {'version 6':>12s} {'version 12':>12s}")
for name in ["no diagram"] + list(DIAGRAM):
    entries = A if name == "no diagram" else visualize(A, DIAGRAM[name], "replacing")
    line = f"{name:>18s}"
    for s in (3, 6, 12):
        t, st, si = measure(entries, s)
        line += f" {f'{t}/{st}/{si}':>12s}"
    print(line)
print()
print(f"{'diagram':>18s} {'replacing: claims':>18s} {'silent':>7s}"
      f" {'duplicating: claims':>20s} {'silent':>7s}")
for name, surfaces in DIAGRAM.items():
    d1 = visualize(A, surfaces, "replacing")
    d2 = visualize(A, surfaces, "duplicating")
    print(f"{name:>18s} {len(d1):18d} {measure(d1, 12)[2]:7d}"
          f" {len(d2):20d} {measure(d2, 12)[2]:7d}")

claims 56 | embedded in text 17 | if all moved to diagrams, embedded 0

           diagram           surface claims  embedded in text  first wrong version
   concept diagram           concept     11                 0                   12
 component diagram              name      7                 3                    5
      flow diagram              flow     16                 9                    3
 interface diagram         signature     22                 5                    2
     mixed diagram signature+flow+name     45                17                    2

when the diagram replaces text - true/stale/silent
           diagram    version 3    version 6   version 12
        no diagram     18/38/24     11/45/28      0/56/39
   concept diagram     18/38/24     11/45/28      0/56/39
 component diagram     18/38/24     11/45/31      0/56/42
      flow diagram     18/38/33     11/45/37      0/56/48
 interface diagram     18/38/29     11/45/33      0/56/44
     mixed diagram     18/38/38     11/45/45      0/56/56

           diagram  replacing: claims  silent  duplicating: claims  silent
   concept diagram                 56      39                   67      50
 component diagram                 56      42                   63      46
      flow diagram                 56      48                   72      55
 interface diagram                 56      44                   78      61
     mixed diagram                 56      56                  101      84

A Sixfold Difference in Lifespan

The top table’s last column is the lesson’s shortest result: 12, 5, 3, 2, 2. Same drawing effort, same page, same reader — and the time a picture stays true changes sixfold. What decides it is not the picture’s beauty, the tool’s quality, or its level of detail; it is what it shows.

The concept diagram stays true to the twelfth version, because how a constraint produces a decision is independent of the product’s field names, call shapes, and step order; it only goes wrong once the decision itself changes. The interface diagram goes wrong at the second version, since what it shows changes every two versions. The course’s second claim holds once more here: what sets the rate of staleness is not form, it is the surface bound to.

This is why the mixed diagram row is the most expensive choice. It carries 45 claims — turning most of the document into a picture — and goes wrong as a whole at version 2: the moment a single signature inside it changes, the reader cannot tell which part of the picture to trust. A diagram “showing everything together” is not a virtue; it is tying its lifespan to its fastest component.

The middle column gives the second cost. The concept diagram takes 0 embedded claims from the text — concept claims could never be embedded to begin with. The flow diagram takes 9, the interface diagram 5, the mixed diagram 17 embedded claims out of the text and into the picture, losing their testability the instant they are moved.

The Document That Goes Silent

The second table shows this loss at the document level, and first says something did not change: the true and stale columns are the same in every row. 18/38 at the third version, 11/45 at the sixth, 0/56 at the twelfth. A diagram does not lengthen or shorten any claim’s life; a diagram is not a maintenance tool.

The only thing that changes is the third number. The diagram-free document has 39 silent claims at the twelfth version. The concept diagram does not change this number — it silenced no voice, since it took claims that were already silent. The component diagram raises it to 42, the interface diagram to 44, the flow diagram to 48. The mixed diagram raises it to 56: at the twelfth version, all of the document’s claims are stale, and none make noise.

The third-version column gives an earlier warning. The flow diagram already raises silent count from 24 to 33 at the third version; the flow surface changes at exactly that version, and its nine embedded claims fall silent at that same instant. The cost of a visual is paid most on the most frequently changing surface.

The decision follows directly from these two tables. What should be drawn is what cannot be embedded in an example. Concept claims can never be tested anyway; moving them into a picture is a free gain — long-lived and silencing no voice. Flow and signature claims are the document’s noise-making part; moving them into a picture is the same as deleting a working test.

When the Diagram’s Source Is Text

The measurement above counted two separate drawbacks together: a diagram cannot be run, and it cannot be scanned. Only one of these comes from the diagram’s nature. The second is a decision about storage format, and it can be undone.

A diagram can be stored two ways. It can stand as an image file — a scan cannot enter it, no diff can be taken between two versions of it, no review can read what changed. Or its source can stand as text, and the picture is generated at build time.

# example diagram source, not executed, showing format only

concept diagram with a text source
  node   measurement-queue  "order must be preserved"
  node   writer-endpoint    "single writer at a time"
  edge   measurement-queue -> writer-endpoint  "the order constraint comes from here"

the same diagram stored as an image file
  (binary content; a scan cannot enter it, no diff can be taken, review
  cannot read it)

In the text-sourced form, the third lesson’s rename scan can enter the picture: when the measurement-queue name changes, the scan finds it exactly as it would in a paragraph. The diagram thereby leaves the “unavoidably missed” class, and its maintenance becomes measurable.

This gain’s limit is clear and should not be overstated. A text source does not make the diagram embedded: the source is not run, only drawn; no test reports a diagram showing a link that no longer exists. The staleness rate does not change either — the picture goes wrong at whatever frequency its surface changes. So the second table’s silence column does not move for this decision. The only thing gained is that silent staleness becomes findable by an audit, not that it becomes heard on its own.

Replacing and Duplicating

The last table measures a second decision: does the diagram replace the text, or is it added beside it? The second case is common and looks harmless — the same thing has been both written and drawn, and the reader uses whichever they prefer.

The numbers say it is not harmless. In duplicating mode, the document climbs from 56 claims to somewhere between 63 and 101, and no new information is added; every added claim copies one already in the text. In return, silent count at the twelfth version rises from 44 to 61 for the interface diagram, and from 56 to 84 for the mixed diagram.

The reason is the same thing the third lesson measured. A copy does not update alongside its source: the text gets fixed, the picture stays as it was, and the reader now holds two contradicting sources. Nothing says which is newer; a picture carries no date.

The rule fits one sentence: if a diagram serves the text, it replaces the text; if not, it only adds a maintenance debt. If a picture says what its neighboring paragraph already says, one of the two is redundant, and the redundant side is the one forgotten come update time.

Summary

• A diagram is a set of claims, and its claims are bound to a surface just like sentences; what separates it is that none of the claims it carries can be run, and a text scan cannot enter it.
• What sets the rate of staleness is the surface, not the drawing: the concept diagram goes wrong every 12 versions, the component diagram every 5, the flow diagram every 3, the interface diagram every 2. A picture showing more than one surface goes stale at its fastest surface’s rate.
• A diagram changes no claim’s lifespan: true and stale counts are the same across every choice (18/38, 11/45, 0/56). The only thing that changes is how many of the stale claims are heard.
• An embedded claim moved from text to picture loses its voice: at the twelfth version, silent count rises from 39 to 48 for the flow diagram, to 56 for the mixed diagram — the whole document goes silent.
• What should be drawn is what cannot be embedded in an example: the concept diagram never raises the silent count at all. A duplicating diagram, adding no new information, grows the claim count to as much as 101 and raises silence to 84.

Next Step

Throughout this topic, the document was always measured as it stood the moment it was written: is the audience definition written, how many steps do the headings shorten, is the term unified, does the example run, what is the picture bound to. All five measurements were decisions made at the writing desk, and all were made once.

But every measurement’s second axis was the version. At the moment it is written, a document is 0/56 stale; at the twelfth version, 56/56; the gap comes not from writing decisions but from time passing. A document, then, is not something written and finished, it is something that lives. The next topic builds exactly this: how a document is versioned alongside code, how it enters review, how its staleness is audited, and through which cycle those silent claims become visible.