--- title: 'Use of Visuals' source: 'https://academia.sh/en/courses/technical-writing/use-of-visuals' course: 'Technical Writing and Documentation' language: en updated: '2026-08-17T18:10:50+00:00' license: 'CC BY-SA 4.0' --- # Use of Visuals What sets a diagram's rate of staleness is not the drawing style but the surface it is bound to: an interface diagram goes wrong at the second version, a concept diagram at the twelfth; since a diagram cannot be run, every stale claim it carries is silent, and a mixed diagram silences all 56 of 56 claims by the twelfth version. 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 ```python """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. ```text # 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.