--- title: 'Audience Definition' source: 'https://academia.sh/en/courses/technical-writing/audience-definition' course: 'Technical Writing and Documentation' language: en updated: '2026-08-17T18:10:50+00:00' license: 'CC BY-SA 4.0' --- # Audience Definition An unwritten prerequisite assumption does not make a claim false, it makes it unreadable; of the 18 claims still true at the third version, the number readable for the new reader is 3 with no audience definition and 18 with it fully written. The previous lesson closed the taxonomy's last gap: with release notes and troubleshooting content added, all six reader questions now fall into a type. The document set knows which question gets answered in which type. A type answers the question only if the reader can resolve the sentence. Being true is not enough: if the reader lacks the prerequisite the sentence assumes, and the document never wrote that assumption, the sentence is not an answer for the reader — it is a **wall**. This lesson's question is: how many claims does a single unwritten prerequisite assumption make unreadable? ## Who the Reader Is Is an Unwritten Decision Every technical text is written for someone. While writing, the author carries a reader in mind: what they know, what they have already set up, which terms they recognize. This table is a set of assumptions, and it always exists. Writing it does not create it, only makes it visible. Not writing it does not remove it, only makes it undiscussable. An unwritten assumption fails in a specific way. The reader reaches the sentence, cannot resolve it, and cannot tell **why**. Was it a term they were supposed to know, or a term the document was supposed to define? A reader who cannot make this distinction either abandons the text or searches in the wrong place. The cost is not the gap in knowledge itself; it is that gap going **unnamed**. A written assumption does not make the reader knowledgeable. All it does is turn the wall into a **sign**: this text assumes you know this. The reader can choose to close that gap, go to another source, or decide the text is not for them. All three are a decision; a wall offers none. ## Two Separate Axes Up to this point, the course measured a single axis: **is a claim still true**. The second axis this lesson adds is **readability**: can the reader resolve that sentence. The two axes are independent and produce four combinations. A claim that is **true and readable** is the document's real capital; it closes the reader's question. A claim that is **true but unreadable** is wasted effort: the sentence is correct, no one benefits from it. A claim that is **stale and readable** is the most damaging; the reader understands it, applies it, and gets it wrong. A claim that is **stale and unreadable** does no harm and no good. This distinction is a measurement result, not a classification choice. The same 56 claims can be counted separately on the two axes, and the two numbers can be seen not tracking each other. Writing a prerequisite assumption does not delay a claim's **staleness**; it makes it **readable**. Since surface frequency does not change, the stale count stays the same across all three regimes. ## What an Audience Definition Writes A measurable audience definition writes four things: the reader's **role**, the prerequisites assumed known, what is left **out of scope**, and what the reader can do by the end of the text. A role is not a person; the same person can read in two different roles in the same day. ```text # example document excerpt, not executed weak audience definition This document is for anyone who wants to use the product. explicit audience definition Role: a reader running an already-installed instance of the invented product for the first time. Assumed known: changing directories and reading files at the command line. Assumed not known: the product's data model, identity layout, concurrent operation. Out of scope: deployment and scaling. By the end, the reader can: run a single measurement and read its output. ``` The difference between the two definitions is not style. From the first, no decision can be drawn about any claim: the set "everyone" excludes no prerequisite, so no sentence can be marked "too much for this reader" or "too little for this reader." The second lets every claim be matched: is the prerequisite it needs on the list or not. **A measurable audience definition is the precondition for a document being auditable.** The out-of-scope line matters in particular, because it closes off a question on its own. A reader looking for deployment learns in the first ten lines that what they are after is not here, and leaves without reading the text. This is not a loss; it is a correct redirection. The measurement's assumptions: - **WD1** — The 56 claims come from the shared fixture: four types, four surfaces, and 17 claims embedded in a runnable example. The oracle is the fixture itself; we know which claim is bound to which surface and which prerequisite it needs, because we wrote it. - **WD2** — Every claim needs one or two prerequisites; prerequisites are chosen from five headings. The distribution is generated by the fixture and does not look at the claim's type — a prerequisite is not a surface. - **WD3** — Three reader roles are measured: the new reader knows one of the five prerequisites, the practitioner three, the maintainer all five. A role is not a person, it is a **reading condition**. - **WD4** — A claim is counted **readable** if every prerequisite it needs is either known to the reader or written in the audience definition. A written assumption does not make the reader knowledgeable; it names the gap and lets the reader close it. The measurement counts this naming as readability. - **WD5** — Three audience-definition regimes are tried: **none** (no assumption written), **partial** (two assumptions written), **full** (all five written). - **WD6** — Readability does not change staleness. Whether a claim is stale looks only at the surface it is bound to and the version; the audience definition does not enter this calculation. ## Measurement ```python """Audience definition: how many claims does an unwritten prerequisite make unreadable. Part 1 - the spread of prerequisites across claims. Part 2 - three reader roles and three audience-definition regimes. Part 3 - at the third version, where true/stale/silent crosses with readability. """ SEED = 20260816 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} PREREQUISITES = ("setup", "command line", "data model", "identity", "concurrency") ROLES = {"new reader": {"command line"}, "practitioner": {"command line", "setup", "data model"}, "maintainer": set(PREREQUISITES)} DEFINITION = {"none": set(), "partial": {"setup", "command line"}, "full": set(PREREQUISITES)} def rng(seed): d = seed % 2147483646 + 1 def r(n): nonlocal d d = (d * 48271) % 2147483647 return d % n return r 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 assign_prerequisites(entries, seed=SEED): """This lesson's one addition: the prerequisites every claim needs.""" r = rng(seed) for i in entries: needed, count = set(), 2 if r(4) == 0 else 1 while len(needed) < count: needed.add(PREREQUISITES[r(len(PREREQUISITES))]) i["prereq"] = needed return entries def stale(i, version): return version // FREQUENCY[i["surface"]] >= 1 def readable(i, role, written): """A prerequisite the reader lacks and the document never wrote makes a claim unreadable.""" return not (i["prereq"] - ROLES[role] - written) A = assign_prerequisites(claims()) print(f"claims {len(A)} | embedded in example {sum(i['embedded'] for i in A)} | " f"needing two prerequisites {sum(len(i['prereq']) == 2 for i in A)}") print("prerequisite " + " ".join(f"{o} {sum(o in i['prereq'] for i in A)}" for o in PREREQUISITES)) print() print(f"{'reader role':>13s}" + "".join(f" {'def. ' + t:>12s}" for t in DEFINITION)) for role in ROLES: line = f"{role:>13s}" for t, written in DEFINITION.items(): line += f" {sum(readable(i, role, written) for i in A):12d}" print(line) print() closed = sum(readable(i, "new reader", set()) for i in A) print("prerequisite written alone for new reader claims opened") for o in PREREQUISITES: opened = sum(readable(i, "new reader", {o}) for i in A) print(f" {o:40s} {opened - closed:6d}") print() print("version 3, new reader true+readable true but unreadable stale silent") for t, written in DEFINITION.items(): true_ = [i for i in A if not stale(i, 3)] stale_ = [i for i in A if stale(i, 3)] silent = [i for i in stale_ if not i["embedded"]] read = sum(readable(i, "new reader", written) for i in true_) print(f" def. {t:12s} {read:14d} {len(true_) - read:20d}" f" {len(stale_):6d} {len(silent):7d}") ``` ``` claims 56 | embedded in example 17 | needing two prerequisites 13 prerequisite setup 16 command line 11 data model 10 identity 13 concurrency 19 reader role def. none def. partial def. full new reader 5 19 56 practitioner 27 27 56 maintainer 56 56 56 prerequisite written alone for new reader claims opened setup 14 command line 0 data model 7 identity 9 concurrency 14 version 3, new reader true+readable true but unreadable stale silent def. none 3 15 38 24 def. partial 7 11 38 24 def. full 18 0 38 24 ``` ## What the Role Charges The second table places the three roles side by side, and the difference between them is not a matter of style, it is a matter of **magnitude**. With no audience definition, the new reader can read **5** of 56 claims. From the same document, the maintainer reads all **56**. Two readers look at the same text, and one of them gets a tenth of it. This table turns the author's most common mistake into a number: the person writing is nearly always in the **maintainer** role. They know the product, they have done the setup, they designed the data model. Looking from their own role, they see the document give **56/56** and find the text sufficient. For the new reader, the number is **5**, and the author cannot see this gap on their own, because the missing prerequisite is not missing **in them**. The middle role is also instructive. The practitioner gets no benefit at all from the partial definition: **27** and **27** are the same. The practitioner already knows the two assumptions the partial definition writes. **An audience definition that is not written for the least-knowing role opens nothing.** A written line's value is measured not by its correctness but by **whose gap it names**. ## How Many Roles a Document Can Carry The table directly raises a question: can the same document carry both the new reader and the maintainer? The numbers say no. A text written for the new reader repeats, line by line, prerequisites the maintainer already knows; a text written for the maintainer gives the new reader **5/56**. There is no setting in between where a single text serves both, because claims opened and lines repeated move in opposite directions. The course's first topic already answered this question: the four types are for different readers. Tutorial is written for the **new reader** role, how-to for the **practitioner** role, reference for the **maintainer** role; explanation is read by all three, but at different depths. So the audience definition is written not for the whole document but **for each type separately**, and each type declares its own role. The measurable consequence is this: if a text has a high count of unreadable claims, one of two separate defects is present. Either the audience definition is missing — the fix is writing a few lines. Or the text is the **wrong type**: a text written as reference is being read like a tutorial, and the fix is not writing, it is **splitting**. The audience definition is the only way to tell these two defects apart; without writing the definition, which defect is present cannot be known. ## The Most Expensive Unwritten Assumption The third table gives the weight of individual assumptions. For the new reader, the **concurrency** and **setup** assumptions each open **14** claims on their own; **identity** opens 9, **data model** opens 7. **Command line** opens **0** — because the new reader already knows it, and writing it adds nothing. The numbers do not add up: 14 + 0 + 7 + 9 + 14 totals **44**, while the full definition opens from 5 to 56, that is, **51** claims. The gap comes from the **13** claims that need two prerequisites; those open only once **both** assumptions are written. This explains why writing an audience definition **piece by piece** pays off less than expected. The practical conclusion: order matters when writing an audience definition, and what should decide the order is **how many claims it opens**, not ease of writing. If a five-line section opens 51 claims, those five lines are the document's most productive five lines. The smallest measurable difference in this set is **1/56 = 0.0179**. The 7, 9, and 14 claims opened by individual assumptions are far above this band and comparable. One assumption opening a single claim more than another cannot be defended with this set; that order would change if the fixture changed. ## Where It Crosses With Staleness The last table joins the two axes, and this is where the lesson's tightest conclusion sits. At the third version, **38** of the document's claims are stale, **24** of those are silently stale, leaving **18** true claims. These three numbers are the same across all three regimes: writing an audience definition does not extend any claim's life. Surface frequency did not change, and neither did staleness. The only column that changes is readability. With no audience definition, of the **18** surviving true claims, the number readable for the new reader is **3**. That is, the document carries **18** still-true sentences at the third version, and the new reader cannot reach **15** of them. With the full definition, **18** of the same 18 sentences become readable. These two numbers need to stand side by side, because that keeps two separate jobs from being confused. Fighting staleness is a **maintenance** job: tracking surfaces, running audits, moving to generated content. Fighting unreadability is a **writing** job, and it is done **once**: once written, the audience definition is bound to the concept surface, the slowest of all surfaces. As long as the product's concepts do not change, the audience definition stays true; a reference line bound to signature goes stale every two versions, while the audience definition renews once every twelve. ## Summary - Who the reader is, is an assumption in every text; writing it does not create it, it makes it discussable. An unwritten assumption's cost is not the reader's lack of knowledge, it is that gap going unnamed. - Readability and staleness are two independent axes: a claim can be true and unreadable, or stale and readable. The most damaging combination is stale and readable. - With no audience definition, the new reader reads **5** of 56 claims, the maintainer all **56**. The author is usually in the maintainer role and cannot see this gap on their own. - The partial definition opens nothing for the practitioner role (**27** and **27**); individual assumptions open **14, 0, 7, 9, 14** claims, and their sum does not reach the **51** the full definition opens, because **13** claims need two assumptions at once. - At the third version, stale **38**, silent **24**, true **18** stay the same across all three regimes; the audience definition changes only how many of those 18 true claims are readable: **3** versus **18**. ## Next Step An audience definition lets a sentence be **resolved**; it does not let it be **found**. In a document written with the full definition, the new reader can now read all 56 claims, but how many lines they need to scan to reach the one claim they are looking for has not been measured yet. The next lesson looks at heading layout: how many steps sit between the reader's question and the claim that answers it, which heading structure shortens that distance, and which surface the heading itself is bound to.