Audience Definition

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.

# 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

"""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.