Tutorial, How-To, Explanation, and Reference

The previous lesson counted the four documents at the moment they were written: 56 claims, four surfaces, 17 embedded examples — and fifty-six of fifty-six claims true. In that table the types were separated only by their composition, not by their outcome, because nothing had changed yet.

This lesson asks two questions at once. The first is about purpose: why do the four types write the same subject separately, and what is the difference between them? The second is about lifespan: once the clock runs two versions, what is left of each? The second question’s answer will follow directly from the first.

The Four Types’ Separate Purpose

The reader does not arrive at a document at random; they arrive with a situation, and that situation determines which type they go to.

A tutorial takes a reader who knows nothing to a result, once. What it promises is not learning but getting a result: by the end, the reader has something working in their hands. This is why a tutorial shows one path, offers no options, and is the only type that addresses the reader directly. A how-to treats the reader as someone who already knows; they have a specific task and want the shortest path to it. What separates it from a tutorial is not the outcome but the entry point: the reader enters not from the start but from the middle.

An explanation is not in the middle of any task. The reader has not come to do something but to understand; their question is “why is it this way,” and the answer is a reason. A reference, on the other hand, is not read, it is looked up. The reader knows what they are looking for, wants to confirm a single field’s type or default, and has no time to spare for reasoning.

The excerpt below shows how the invented “Measurement Station” product’s four documents write the same option.

# how the invented product's four types write the same option
# example text, not executed

tutorial       To take your first measurement, run
               `station start --interval 5`. A line drops every five seconds.

how-to         To change the sampling frequency, give the `--interval`
               option an integer in seconds.

explanation    Interval is the width of the sampling window. As the
               window narrows, noise in individual readings rises;
               as it widens, sudden changes get lost in the average.

reference      --interval <seconds>
               type: integer   default: 60   lower bound: 1

What really separates the types is not what they write but what they do not write. A tutorial gives no reason — giving one would stop the reader and delay reaching the result. A how-to text does not start from the beginning; it assumes the reader already has the setup. An explanation gives no steps; the moment it does, a path is born that the reader will follow, and that path is left unmaintained. A reference does not teach; if it tries to explain what a field is for, the same reasoning ends up sitting in two places, and the two go stale at two separate speeds. These four negative rules do more work than four positive ones would.

All four are correct, and all four are necessary. The first cost of mixing up the types is that the reader cannot find what they came for: a reader looking for a reason who lands on a tutorial finds only steps; a reader with a task who lands on an explanation reads twenty lines and finds no command. But that is not the cost this lesson measures. What is measured is what the four types lose in the face of the same event.

Same Event, Four Separate Bills

In the excerpt above, look not at how many claims each of the four texts carries, but at what their claims are bound to. The tutorial’s line describes an order — flow. The how-to line carries both the order and the option’s shape. The explanation line builds a reason — concept. Every cell of the reference line is the interface’s shape: name, type, default, lower bound. Everything the reference writes is signature.

Now let the product’s second version ship, and let exactly one thing happen: the signature surface changes once. The option’s name, type, or default shifts. No one touched the documents; all four texts still stand as they were yesterday. This single event does not cut the same bill for the four types, and the measurement counts exactly that.

The measurement’s assumptions:

• DT9 — The setup is the previous lesson’s set: 56 claims, four types, four surfaces. Type definitions and surface frequencies are unchanged.
• DT10 — The version counter runs only the surfaces. A surface changes once at every version that is a multiple of its frequency; signature every 2, flow every 3, name every 5, concept every 12.
• DT11 — A claim is stale if the surface it is bound to has changed at least once by the measured version. Staleness is not undone: no one corrects the document in this measurement.
• DT12 — The measurement builds versions 0, 1, and 2. Later versions are not built in this lesson and their numbers are not read from here.
• DT13 — The reader has six questions, and every question lands on a single type or on none. The question set is the course’s constant; this lesson does not expand it.
• DT14 — A question is considered answered if a type carrying its answer exists. Whether the answer is still true is measured in a separate column; the two are not mixed.
• DT15 — An answer’s confidence is the share of that type’s claims still true at the measured version. This is not a probability, it is the set’s ratio.
• DT16 — If two types are merged onto one page, their claims are added together and the reader sees the whole page as a single text; the page’s confidence is the merged set’s true share.
• DT17 — The set’s resolution is 1/56; single-claim differences are meaningful, anything smaller cannot be defended with this set.

Measurement

"""Four types, four separate lifespans: what is left at version two.

Part 1 - the true/stale/silent triple for each type at versions 0, 1, and 2.
Part 2 - six reader questions, the type that answers them, and that answer's strength at version two.
"""
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}
# Question the reader brings -> answering type; None means no type answers it.
QUESTIONS = {
    "where do I start": "tutorial",
    "how do I do this": "how-to",
    "why is this the way it is": "explanation",
    "what type is this field": "reference",
    "what version did this change in": None,
    "why is this not working": None,
}


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):
    """Stale if the surface it is bound to has changed at least once by this version."""
    return version // FREQUENCY[i["surface"]] >= 1


def measure(version, entries):
    result = {}
    for kind in TYPES:
        group = [i for i in entries if i["type"] == kind]
        gone_stale = [i for i in group if stale(i, version)]
        silent = [i for i in gone_stale if not i["embedded"]]
        result[kind] = (len(group), len(group) - len(gone_stale),
                         len(gone_stale), len(silent))
    return result


L = claims()
print(f"claims {len(L)} | types {len(TYPES)}")
print()
print(f"{'version':>7s} {'changed surface':<16s} " +
      " ".join(f"{t:>15s}" for t in TYPES))
print(f"{'':7s} {'':16s} " + " ".join(f"{'true/stale/silent':>15s}"
                                      for _ in TYPES))
for s in (0, 1, 2):
    changed = [y for y in FREQUENCY if s // FREQUENCY[y] >= 1] or ["-"]
    d = measure(s, L)
    print(f"{s:7d} {', '.join(changed):<16s} " +
          " ".join(f"{f'{d[t][1]}/{d[t][2]}/{d[t][3]}':>15s}" for t in TYPES))

print()
d2 = measure(2, L)
print(f"{'question':<28s} {'answering type':<14s} {'version 2':>9s} {'confidence':>10s}")
for q, t in QUESTIONS.items():
    if t is None:
        print(f"{q:<28s} {'-':<14s} {'-':>9s} {'-':>10s}")
    else:
        _, true, _, _ = d2[t]
        total = d2[t][0]
        print(f"{q:<28s} {t:<14s} {f'{true}/{total}':>9s} "
              f"{true / total:10.4f}")
answered = sum(1 for t in QUESTIONS.values() if t)
print(f"reader questions {len(QUESTIONS)} | answered by one type {answered} | "
      f"answered by no type {len(QUESTIONS) - answered}")

print()
e_true, e_total = d2["explanation"][1], d2["explanation"][0]
r_true, r_total = d2["reference"][1], d2["reference"][0]
print(f"at version two: explanation {e_true}/{e_total} = {e_true / e_total:.4f}, "
      f"reference {r_true}/{r_total} = {r_true / r_total:.4f}")
print(f"lifespan ratio {e_true / e_total / (r_true / r_total):.3f}x")

print()
# Two types kept separate: what the reader sees when merged onto one page.
MERGED = ("tutorial", "reference")
print(f"{'page':<24s} {'claims':>6s} {'true':>5s} {'stale':>5s} {'confidence':>10s}")
for kind in MERGED:
    t, true, stale_n, _ = d2[kind]
    print(f"{kind + ' (separate)':<24s} {t:6d} {true:5d} {stale_n:5d} "
          f"{true / t:10.4f}")
t = sum(d2[x][0] for x in MERGED)
true = sum(d2[x][1] for x in MERGED)
print(f"{'both on one page':<24s} {t:6d} {true:5d} {t - true:5d} "
      f"{true / t:10.4f}")

claims 56 | types 4

version changed surface         tutorial          how-to     explanation       reference
                         true/stale/silent true/stale/silent true/stale/silent true/stale/silent
      0 -                         15/0/0          14/0/0          12/0/0          15/0/0
      1 -                         15/0/0          14/0/0          12/0/0          15/0/0
      2 signature                 12/3/1           9/5/2          11/1/1         2/13/13

question                     answering type version 2 confidence
where do I start             tutorial           12/15     0.8000
how do I do this             how-to              9/14     0.6429
why is this the way it is    explanation        11/12     0.9167
what type is this field      reference           2/15     0.1333
what version did this change in -                      -          -
why is this not working      -                      -          -
reader questions 6 | answered by one type 4 | answered by no type 2

at version two: explanation 11/12 = 0.9167, reference 2/15 = 0.1333
lifespan ratio 6.875x

page                     claims  true stale confidence
tutorial (separate)          15    12     3     0.8000
reference (separate)         15     2    13     0.1333
both on one page             30    14    16     0.4667

Reading Version Two

Version one costs nothing at all: all four types stand exactly as they were written. The reason is not that the document was left unread, it is that even the fastest-changing surface has not moved yet. Staleness is not a continuous erosion; it arrives step by step, and the first step is version two.

Only one surface changes at version two: signature. The bills split as follows — tutorial loses 3, how-to 5, explanation 1, reference 13 claims. Same event, four separate amounts. No one wrote one of the four texts more carelessly; all four were written the same day, with the same care. The difference is only what they were bound to.

The extremes say this in a single line. The hand-written reference loses 13 of its fifteen claims and is left at 2/15. Explanation keeps 11 of its twelve claims: 11/12. The ratios are 0.1333 and 0.9167, and the gap between them is 6.875 times. The same writing effort, a lifespan more than six times as long.

The practical counterpart of this number is: staleness speed is set not by the type but by the surface it is bound to. The sentence “reference goes stale fast” looks like a property of the type, but it is not; reference goes stale fast because 13/15 of its claims hang on the fastest-changing surface. Explanation lives long in the same way, because 9/12 of it is bound to the slowest surface. The way to slow a reference down is not writing more carefully, it is detaching the claim from the signature — and there is a way to do that; the fourth lesson measures it.

The silent column says a second thing. Only 1 of the tutorial’s 3 stale claims is silent; 13 of the reference’s 13 stale claims are all 13 silent. Damage in a tutorial breaks an example, so it eventually explodes in someone’s hands; damage in a reference explodes nowhere. The type that loses the most is the type that advertises its loss the least.

The Cost of Mixing

The reason usually given for separating the four types is that the reader finds what they are looking for. The last table gives a second, harsher reason. When tutorial and reference are merged onto a single page, the page carries 30 claims, and by version two 16 of them are stale: confidence 0.4667.

The number reads like this: merging does not average lifespans, it pulls toward the faster one. Kept separate, a reader of the tutorial was reading a 0.8000 text; once the same content sits on the same page as the reference, that reader is now reading a 0.4667 page. Not a single sentence of the tutorial changed. What changed is that the reader can no longer tell what they are looking at — the four true lines at the top of the page and the thirteen stale lines underneath sit under the same heading, with the same apparent confidence.

The separation is therefore not a layout preference, it is a measurement condition: without splitting claims into types, how much of which section still stands cannot be measured, and if it cannot be measured, maintenance cannot be pointed anywhere. A single page hides which section has rotted.

The Taxonomy’s Limit

The bottom table measures the four types from the reader’s side. The reader arrives at a document with six separate questions. Four land cleanly on one type: “where do I start” on the tutorial, “how do I do this” on the how-to text, “why is this the way it is” on the explanation, “what type is this field” on the reference. The count is clear: 4 of six questions are answered by one type.

But being answered is not the same as being answered correctly. The confidence column, at that same version two, gives: the answer to “why is this the way it is” is 0.9167 reliable, the answer to “what type is this field” is 0.1333. The reader’s most certain-looking question — a field’s type either is or is not something — gets the least reliable answer. Reference is assumed reliable because it is written with certainty; but certainty does not just leave unclear when staleness began, it hides it.

Two questions remain, and they land on none of the four types: “what version did this change in” and “why is this not working.” This is not a gap, it is the taxonomy’s limit. The four types describe the product as it is now; none carries time, which is why the first goes unanswered. All four describe the correct path; none enters from the wrong path, which is why the second goes unanswered. Neither question is invented out of nowhere: the table just above produced the first — a reader looking at a 2/15 reference has to ask which claim dropped when. This course’s fifth and sixth lessons build exactly these two questions.

Summary

• The four types meet the reader’s separate moments: tutorial delivers a result, how-to closes a task, explanation builds a reason, reference confirms; tutorial is the only type that addresses the reader directly.
• Version one costs nothing; staleness arrives in steps, and the first step is version two, because the fastest surface changes once every two versions.
• A single signature change cuts a separate bill for the four types: tutorial loses 3, how-to 5, explanation 1, reference 13 claims.
• The hand-written reference is left at 2/15 (0.1333), explanation at 11/12 (0.9167); the lifespan gap is 6.875 times. Staleness speed is set by the surface bound to, not the type.
• 13 of reference’s 13 stale claims are silent; the type that loses the most advertises its loss the least. Merging tutorial and reference onto one page drops confidence from 0.8000 to 0.4667: merging does not average lifespans, it pulls toward the faster one.
• 4 of six reader questions land on one type, 2 land on none: “what version did this change in” and “why is this not working” — that is the taxonomy’s limit.

Next Step

The four documents measured so far described the product itself. Other documents also sit inside a repository, and their readers are different: someone looking at the repository for the first time, someone who wants to contribute, someone looking for why a decision was made the way it was. The next lesson puts these documents through the same measure — which surfaces does the readme bind to, which one the contribution guide, which collapses in a single version, and which stays true for years?