--- title: 'Tutorial, How-To, Explanation, and Reference' source: 'https://academia.sh/en/courses/technical-writing/tutorial-how-to-explanation-and-reference' course: 'Technical Writing and Documentation' language: en updated: '2026-08-17T18:10:49+00:00' license: 'CC BY-SA 4.0' --- # Tutorial, How-To, Explanation, and Reference The four types write the same subject with separate purposes and go stale at separate speeds: a single signature change drops 13 of reference's 15 claims by version two, leaving 2, while explanation keeps 11 of 12 — a 6.875-times gap; four of six reader questions land on one type, two land on none. 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**. ```text # 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 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 ```python """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?