The Scope of Technical Writing

The previous course measured a review’s number not by how many people looked but by how many axes were looked at and how many chunks were read, and it drew a boundary at its close: review looks at what was written; writing what was not written is a separate job. What was measured there was whether a defect was found — the change sat on the table, the reviewer looked at it, and the measurement was made in a single moment.

A document does not work that way. A document is true the day it is written; what is interesting is what comes after. What this course measures is whether what was written is still true, and, when it turns false, whether that gets noticed. This lesson sets the unit of that measure: how many sentences of a document can be true or false, what those sentences depend on, and who notices when the thing they depend on changes.

Three Content Sets

Technical writing is not a single job; its reader and its trigger form three separate sets.

Product content tells someone who has never used the product what it is; its trigger is a decision and its reader is not yet a user. Developer content tells someone who will use or extend the product how it works; its trigger is a task. Support content is read when something has gone wrong; its trigger is a failure, and its reader arrives holding a symptom.

The three are not measured by the same yardstick. Product content’s correctness is usually a positioning question and has no technical oracle. This course measures developer content: text made of sentences that can be said to be true or false, with a counterpart sitting in the code. Support content enters the measure later, in its own lesson; product content stays outside the course.

Developer content splits into four types, and the four meet the same reader at different moments. A tutorial takes someone who knows nothing to a result, once. A how-to takes someone with a specific task to that task’s steps. An explanation tells why something is the way it is. A reference is the line-by-line listing of fields, options, and return values. These four names stay fixed for the whole course.

A Document’s Number Is Not Its Length

Measuring a document by page count does not work, because length says neither what question the reader is answering nor whether the text is true. This course’s unit is the claim: every sentence in a document that could be true or false is a claim. A polished paragraph can carry zero claims; a three-line setup section can carry four.

The excerpt below is taken from a product invented for this course alone — a measurement tool called “Measurement Station.”

# an excerpt from the invented product's readme
# example text, not executed

## Setup

Install the package and run the `station start` command.
The command takes the `--interval` option in seconds.
The default profile's name is `local`.
The interval sets the measurement's sampling window; the
narrower the window, the higher the measurement noise.

Four sentences, four claims. All four are true today. But the four are not bound to the same thing, and this distinction carries the whole course.

The Measure’s Wrong Proxies

Before moving to counting claims, three commonly used proxies need to be ruled out; all three are easy to tally, and all three count the wrong thing.

Length. Page or word count measures the effort written, not its correctness. A two-thousand-word tutorial can be entirely wrong; a ten-line section can be completely correct. As length grows, claim count grows with it, meaning a longer document is more falsifiable — an indicator pointing the wrong way.

Last-updated stamp. The date at the top of a document says the document was touched; it does not say it was verified. A spelling fix refreshes the stamp and leaves the forty claims underneath untouched. The reverse also holds: an explanation untouched for a year is still entirely true if the concept it is bound to has not changed. The stamp measures the document’s age; what is being asked is the age of the surface it is bound to.

Coverage ratio. The question “what percentage of endpoints are documented” measures absence, not wrongness. An undocumented endpoint sends the reader to the source; a wrongly documented endpoint sends the reader to the wrong place and does not say it did. Coverage ratio can rise while correctness falls, because the two count different things.

The three proxies share one flaw: none looks at what the document depends on. The measure has to look there.

What a Claim Is Bound To

Every claim is bound to a surface: the thing its correctness is borrowed from.

Signature is the interface’s shape — an option’s name, a field’s type, the parameters a function takes. The --interval option taking seconds is a signature claim. Flow is the order of steps: first install, then run. Name is what something is called; the default profile being called local is a name claim. Concept is why something is the way it is; noise rising as the window narrows is a concept claim.

Surfaces do not change at the same rate, and this is the course’s constant: signature changes once every two versions, flow once every three, name once every five, concept once every twelve. A claim goes stale the moment the surface it is bound to changes — the text stays the same, its counterpart shifts.

The first result that follows is this: a sentence’s lifespan is determined not by the writer’s care but by what the sentence is bound to. Of two sentences written with equal attention, one lives two versions, the other lives twelve.

What Makes Noise and What Does Not

There is a second distinction, and it is the course’s own contribution. Some claims are embedded in a runnable example: they sit inside a command line, inside a code snippet. When an embedded claim goes stale, the example fails to run — the moment someone runs it, it makes noise. When a claim that is not embedded goes stale, nothing happens: the text stays as it is, no one notices, and the reader reads the wrong sentence believing it is true. This is called silent staleness.

Making noise is also bound to the surface. A concept claim can never be embedded; the sentence “noise rises as the window narrows” is not something that can be run. A signature claim can be embedded but does not have to be: a field type sitting in a table row and a field type sitting inside an example call say the same thing, one is silent, the other is not.

Who hears the noise is also fixed. The new reader copies the example and runs it; if an embedded claim has gone stale, they are the first to hit the error, and most of the time they do not know it is the document’s defect — they suspect their own setup. The maintainer reads the document, does not run it; they notice a silent claim is wrong only if they read it on a subject they already know — that is, exactly where they needed no help. This is why silent staleness persists: the person who could see it does not look there, and the person who looks there cannot see it.

The measurement’s assumptions:

• DT1 — The invented product has four documents, of types tutorial, how-to, explanation, reference. The definitions of the four types do not change throughout the course.
• DT2 — Together the four carry 56 claims. A claim is a single sentence in a document that could be true or false; style, headings, and links do not count as claims.
• DT3 — Every claim is bound to exactly one surface: signature, flow, name, or concept. A sentence bound to more than one surface is counted in this measurement as split into two claims.
• DT4 — Surfaces change at a fixed rate: signature once every 2 versions, flow every 3, name every 5, concept every 12. These four numbers are not changed in any lesson of this course.
• DT5 — A type’s surface mix comes from how it is written: tutorial and how-to narrate steps, so they are flow-heavy; reference lists fields, so it is signature-heavy; explanation builds reasoning, so it is concept-heavy.
• DT6 — The share of claims embedded in a runnable example varies by type: tutorial 0.60, how-to 0.70, explanation 0.10, reference 0.00. No claim bound to the concept surface can be embedded.
• DT7 — The oracle is the setup itself: which claim is bound to which surface and when it will go stale is known because we wrote the setup. A real repository has no such knowledge, and this course’s later lessons ask how to produce it.
• DT8 — The set’s resolution is 1/56; a single claim is the smallest distinguishable difference in this measurement.

Measurement

"""The composition of a document the moment it is written: 56 claims, four types, four surfaces.

Part 1 - claims per type, surface mix, and claims embedded in an example.
Part 2 - the claims a single surface change drops, and the share that stays silent.
"""
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},
}
SURFACES = ("signature", "flow", "name", "concept")
# Share of claims embedded in a runnable example: these make noise when they go stale.
EMBEDDED = {"tutorial": 0.60, "how-to": 0.70, "explanation": 0.10,
            "reference": 0.00}


def claims():
    """Each claim: its type, the surface it is bound to, whether it is embedded."""
    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


L = claims()
print(f"claims {len(L)} | types {len(TYPES)} | surfaces {len(SURFACES)} | "
      f"embedded in example {sum(i['embedded'] for i in L)}")
print()
print(f"{'type':<14s} {'claims':>6s} {'signature':>9s} {'flow':>5s} {'name':>4s} "
      f"{'concept':>7s} {'embedded':>8s} {'silent':>6s}")
for kind in TYPES:
    g = [i for i in L if i["type"] == kind]
    emb = sum(i["embedded"] for i in g)
    print(f"{kind:<14s} {len(g):6d} "
          + " ".join(f"{sum(1 for i in g if i['surface'] == s):>{w}d}"
                     for s, w in zip(SURFACES, (9, 5, 4, 7)))
          + f" {emb:8d} {len(g) - emb:6d}")
print(f"{'total':<14s} {len(L):6d} "
      + " ".join(f"{sum(1 for i in L if i['surface'] == s):>{w}d}"
                 for s, w in zip(SURFACES, (9, 5, 4, 7)))
      + f" {sum(i['embedded'] for i in L):8d} "
      f"{sum(not i['embedded'] for i in L):6d}")

print()
print("at the moment of writing (version 0) - true/stale/silent")
print("  " + " | ".join(f"{t} {len([i for i in L if i['type'] == t])}/0/0"
                        for t in TYPES))

print()
print(f"{'changed surface':<16s} {'claims drop':>11s} {'share':>6s} "
      f"{'audible':>7s} {'silent':>6s} {'silent share':>12s}")
for s in SURFACES:
    d = [i for i in L if i["surface"] == s]
    audible = sum(i["embedded"] for i in d)
    print(f"{s:<16s} {len(d):11d} {len(d) / len(L):6.4f} {audible:7d} "
          f"{len(d) - audible:6d} {(len(d) - audible) / len(d):12.4f}")

claims 56 | types 4 | surfaces 4 | embedded in example 17

type           claims signature  flow name concept embedded silent
tutorial           15         3     9    2       1        8      7
how-to             14         5     6    2       1        9      5
explanation        12         1     1    1       9        0     12
reference          15        13     0    2       0        0     15
total              56        22    16    7      11       17     39

at the moment of writing (version 0) - true/stale/silent
  tutorial 15/0/0 | how-to 14/0/0 | explanation 12/0/0 | reference 15/0/0

changed surface  claims drop  share audible silent silent share
signature                 22 0.3929       5     17       0.7727
flow                      16 0.2857       9      7       0.4375
name                       7 0.1250       3      4       0.5714
concept                   11 0.1964       0     11       1.0000

Reading the Composition

The third block gives the course’s starting point: on the day it is written, all four documents are flawless. All fifty-six of fifty-six claims are true, stale is 0, silent is 0. The measure distinguishes nothing at this point — this is why measuring quality at the moment of writing does not measure a document at all.

The top table carries the real information. Tutorial and reference both carry 15 claims; they look like two equally long documents. Their compositions are exact opposites: 9 of the tutorial’s 15 claims are bound to flow, 13 of the reference’s 15 are bound to signature. The embeddedness column separates them completely — 8 claims are embedded in an example in the tutorial, 0 in the reference. Reference is the one type that makes no noise at all when it goes stale, and it does this not because it is a type, but because it carries no example at all.

Explanation’s embedded claim count is also 0. But the reason is different: 9 of its claims are bound to concept, and a concept claim cannot be embedded. Two types produce the same number of silent claims, one because it never writes an example, the other because it cannot.

The total row reads in a single line: 17 of the embedded claims, all 17, belong to the tutorial and how-to types. All the noise a four-type document set produces comes from two types; the other two, carrying 27 claims between them, produce no noise at all. This does not make those two types bad — explanation’s job is reasoning, reference’s job is listing — but it does say: a document set’s maintenance warning comes not from the whole set, but from the part that carries examples. The bigger the part that carries no example grows, the quieter the set becomes.

The bottom table gives the cost of a single change. When the signature surface changes once, 22 claims drop — 0.3929 of the set, more than a third. Only 5 of these make noise; 17 drop silently, meaning 0.7727 of the signature change goes unheard. Signature is also the fastest-changing surface: once every two versions. The most crowded and quietest set hangs on the most frequently changing surface.

The comparison reverses on the flow surface: 16 claims are bound to flow, 9 make noise, and the silent share drops to 0.4375. Flow claims narrate steps, steps enter examples, examples break. On the concept surface, the silent share is 1.0000 — none of the eleven claims make noise — but concept changes only once every twelve versions, meaning these eleven claims are both the longest-lived and, when they go stale, the least visible.

From here the course’s measure takes its full shape: a document’s number is not its length, it is the number of claims still true — and how many of the ones that go stale stay silent. You cannot read which of two documents is better maintained from its prose quality; you can read it from its composition.

Summary

• Technical writing splits into three sets — product, developer, support content — and this course measures developer content, the kind that can be said to be true or false.
• A document’s unit is the claim: a single sentence that can be true or false. The four types’ documents together carry 56 claims, and length does not give this number.
• Every claim is bound to a surface — signature 22, flow 16, name 7, concept 11 — and surfaces change at different rates: once every 2, 3, 5, and 12 versions.
• 17 claims are embedded in a runnable example and make noise when they go stale; the remaining 39 go stale silently. Reference’s embedded claim count is 0, and so is explanation’s.
• A single change on the signature surface drops 22 claims (0.3929) and 17 of those are silent (0.7727); the same computation on flow gives 16 claims and 0.4375 silence.

Next Step

This lesson only named the four types and counted their compositions; it did not measure how much of each stands up over time. The next lesson runs the clock: what state are the same four documents in two versions later? How many of the hand-written reference’s fifteen claims survive, how many of explanation’s twelve does it keep, and how many times larger does the gap between the two types turn out to be? The same lesson asks a second question too: the reader arrives at a document with six separate questions; how many of those questions do these four types answer?