Style Guide

The previous lesson’s entire measurement leaned on a single silent assumption: the reader can match the word in their own question to the word in the heading. This assumption does not always hold. If a document gives the same thing two names in two places, the word the reader is holding matches only one of the two.

This lesson’s question is the cost of dual naming: when the same concept is called by two names, how many claims can the reader reach, and how many stay ambiguous? A second question stands beside it: what happens when the document called a style guide gets written without answers to questions like this?

Not a Rule, a Measure

Most style guides are written as a list of prohibitions, and a list like this fails for two reasons. First, the person applying the rule cannot recognize an exception, because they do not know what the rule protects; the rule gets applied blindly or broken blindly. Second, the rule cannot be argued about: two authors who think differently have only preference in hand, not a measure.

A measurably written item is different. It writes the rule’s name, what it measures, how the measure is taken, and where the rule falls.

# example style guide entry, not executed

item written as a mandate
  Rule 7: do not write "node" instead of "unit."

item written as a measure
  Rule 7 — single term.
  What it measures: the number of claims the reader can find by searching
              with their own word, and the number of claims a rename scan
              misses when the term changes.
  How it is measured: every claim mentioning a term is counted; the ones
              written with the primary name are found, the ones written
              with the second name are missed.
  Where it falls: when a term genuinely has two names on the product's
              surface. In that case the document writes both, declares
              one primary, and mentions the other only next to the
              definition.

The second form does not carry a prohibition; it carries a quantity. When the author wants to break the rule, they see what they lose and can make the decision with a reason. Written this way, a style guide is not a document of taste, it is a measurement document, and it is auditable just like the document itself.

The Ambiguity Two Names Produce

The same concept being called by two names opens three separate readings in the reader’s head, and the reader cannot tell from the text which one is correct.

The first reading: the two are the same thing, the author varied the wording. The second: the two are separate things, an unknown distinction exists and should be learned first. The third: one is old, the product was once named that way and the document was never updated. All three are supportable by the text; the reader has to place a bet.

The cost of this ambiguity is not only slowing down. A reader who picks the second reading wastes time searching for a distinction that does not exist; one who picks the first, if the names really do correspond to different things, performs the wrong operation. The measurement therefore counts ambiguous claims in a separate column: they are not wrong, they hold a decision pending.

Voice Consistency

The second rule is not about terms; it is about whom the sentence is speaking about. A technical sentence either addresses the reader — states a task to be done — or narrates the system — states something that happens on its own. When the two mix, the reader makes the same decision in every sentence: is this a job for me, or something that just happens?

Voice consistency moves this decision up to the level of the type. Tutorial and how-to address the reader, since both carry out a task the reader has in hand; explanation and reference narrate the system, since neither expects an action from the reader. Tied to type, voice is not resolved sentence by sentence; it is learned once, at the top of the section.

What this rule measures is not a prohibition either: it is the number of claims where the reader can tell whom the action falls to.

The measurement’s assumptions:

• WD21 — The 56 claims come from the shared fixture: four types, four surfaces, 17 claims embedded in a runnable example. The oracle is the fixture itself.
• WD22 — The only thing this lesson adds is the term every claim mentions, the name it uses, and its voice. All three are chosen by the fixture’s generator and do not look at the claim’s surface.
• WD23 — There are eight terms, and each term can have two names. If a term is unified, all of its claims use the primary name; if not, every claim uses one of the two names.
• WD24 — The reader knows the primary name; they cannot reach a claim written with the second name by searching.
• WD25 — If a term appears in the document under both of its names, all of that term’s claims are counted ambiguous; the reader cannot tell from the text whether the two names point to the same thing.
• WD26 — Three naming regimes are tried: free (no term unified), partial (the four most frequent terms unified), single term (all eight unified).
• WD27 — A rename scan searches for the primary name and fixes every claim it finds. A claim written with the second name stays outside the scan and keeps carrying the old name; if that claim is not embedded in a runnable example, it makes no noise at all.

Measurement

"""Style guide: what the same concept called by two names produces in the reader.

Part 1 - term distribution and true/stale/silent at the fifth version.
Part 2 - three naming regimes: claims found and claims ambiguous.
Part 3 - voice consistency and what the rename scan misses.
"""
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}
TERMS = ("measurement", "node", "authorization", "threshold", "log", "channel",
         "tag", "checksum")
# The voice each type establishes with the reader: is the job the reader's, or the system's.
VOICE = {"tutorial": "reader", "how-to": "reader",
         "explanation": "system", "reference": "system"}


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_term(entries, seed=SEED):
    """This lesson's one addition: every claim's term, chosen name, and voice."""
    r = rng(seed)
    for i in entries:
        i["term"] = TERMS[r(len(TERMS))]
        i["second_name"] = r(2) == 0
        i["voice"] = "reader" if r(2) == 0 else "system"
    return entries


def stale(i, version):
    return version // FREQUENCY[i["surface"]] >= 1


A = assign_term(claims())
ranked = sorted(TERMS, key=lambda t: -sum(i["term"] == t for i in A))
REGIME = {"free": (), "partial": tuple(ranked[:4]), "single term": TERMS}


def by_second_name(i, unified):
    """If a term is not unified, a claim may use either of its two names."""
    return i["second_name"] and i["term"] not in unified


print(f"claims {len(A)} | terms {len(TERMS)} | embedded in example "
      f"{sum(i['embedded'] for i in A)}")
print("term distribution: " + ", ".join(
    f"{t} {sum(i['term'] == t for i in A)}" for t in TERMS))
s5 = [i for i in A if stale(i, 5)]
print(f"version 5 - true {len(A) - len(s5)} | stale {len(s5)} | silent "
      f"{sum(not i['embedded'] for i in s5)}  (the name surface changes at the fifth version)")
print()
print(f"{'style regime':>12s} {'dual-named terms':>16s} {'found by own name':>20s}"
      f" {'ambiguous claims':>16s}")
for name, unified in REGIME.items():
    dual = [t for t in TERMS if t not in unified
            and len({i["second_name"] for i in A if i["term"] == t}) == 2]
    found = sum(not by_second_name(i, unified) for i in A)
    ambiguous = sum(i["term"] in dual for i in A)
    print(f"{name:>12s} {len(dual):16d} {found:20d} {ambiguous:16d}")
print()
print(f"{'voice regime':>12s} {'written in type voice':>22s}"
      f" {'reader/system mixed':>22s}")
matches = sum(i["voice"] == VOICE[i["type"]] for i in A)
print(f"{'mixed':>12s} {matches:22d} {len(A) - matches:22d}")
print(f"{'unified':>12s} {len(A):22d} {0:22d}")
print()
print(f"{'rename scan':>16s} {'scanned':>8s} {'found':>8s} {'missed':>7s}"
      f" {'silent of missed':>16s}")
for name, unified in REGIME.items():
    missed = [i for i in A if by_second_name(i, unified)]
    print(f"{name:>16s} {len(A):8d} {len(A) - len(missed):8d} {len(missed):7d}"
          f" {sum(not i['embedded'] for i in missed):16d}")

claims 56 | terms 8 | embedded in example 17
term distribution: measurement 7, node 10, authorization 4, threshold 8, log 8, channel 6, tag 7, checksum 6
version 5 - true 11 | stale 45 | silent 28  (the name surface changes at the fifth version)

style regime dual-named terms    found by own name ambiguous claims
        free                7                   25               52
     partial                3                   42               19
 single term                0                   56                0

voice regime  written in type voice    reader/system mixed
       mixed                     28                     28
     unified                     56                      0

     rename scan  scanned    found  missed silent of missed
            free       56       25      31               23
         partial       56       42      14                8
     single term       56       56       0                0

The Reader Who Cannot Find Half

The top table’s middle column is the lesson’s headline number. In the free regime, when the reader searches with the name they know, they find 25 of 56 claims. The remaining 31 stand in the document, stand true, but go unfound by the reader’s word. This is not a writing defect, it is an access defect, and it adds to the distance the previous lesson measured: even finding the right section, the reader does not recognize the sentence.

The column on the right is heavier. In the free regime, 52 claims are ambiguous — nearly all 56 make the reader ask “are these two names the same thing” once again. Ambiguity spreads not to individual claims but to the term: the moment a term is called by two names, every one of that term’s claims becomes ambiguous, including the ones not written with the second name.

The left column reveals a detail: in the free regime, 7 of the eight terms appear under two names, the eighth does not. That term’s four claims all happened to pick the same name. With no rule, uniqueness can be reached by coincidence; but that is not a discipline, and it breaks with the next sentence written. The rule’s function is not to produce uniqueness, it is to guarantee it.

The middle row tells how the rule should be ordered. Unifying the four most frequent terms raises found from 25 to 42, and lowers ambiguous from 52 to 19. Half the terms closes two-thirds of the ambiguity. If a style guide cannot be applied top to bottom, ordering terms by frequency pays off most of it in the first move.

When Voice Mixes

The second table gives a blunter result: in the mixed regime, 28 of 56 claims are written in their type’s voice, 28 are not. In one out of every two sentences, the reader decides for themselves whom the action falls to. In a tutorial, a sentence in the system’s voice hides the task to be done; in a reference, a sentence in the reader’s voice invents a task that does not exist.

This 28 is from the fixture, and what matters is not its size but that the number of decisions is proportional to the number of claims. The voice-consistency rule brings this decision down from 56 times to one: once the type is chosen, the voice is chosen with it. This is what the rule measures, and there is no case for writing it as a matter of taste.

Who Decides the Primary Name

The measurement does not say one thing: which name becomes primary. This gap is the rule’s most critical spot, because if filled wrong, the single-term rule raises the number to 56 and gains the reader nothing.

The word in the reader’s hand does not come from the document; it comes from the product’s surface. The reader has read the option they typed, the field they saw, the message they received. If the document picks a name that is internally consistent but absent from the product, the word the reader brings touches no claim. The rule’s correct form is therefore not “use a single name” but “the primary name is the name that appears on the product’s surface.”

The case where a term genuinely has two names in the product is where the rule falls, and it genuinely happens: the same setting has a command-option name and a configuration-key name. For a term like this, the document writes both once, declares which is primary, and uses only the primary name after that. Because the second name appears once, next to the definition, the reader can make the match; because it does not spread into the claims, the scan does not miss it. Ambiguity is thereby brought down from 56 claims to a single line.

This link ties the term’s job directly to the name surface. When the product’s name changes, the document’s name has to change with it, and this is not a matter of style maintenance, it is staleness maintenance.

The Rename Scan

The last table ties the lesson to the course’s own axis. When the product renames a term, the maintainer scans the text and fixes what they find. In the free regime, the scan finds 25 claims and misses 31 — because the scan searches for the primary name, and the missed ones are written with the second name.

23 of the missed are silent. Since these claims are not embedded in a runnable example, they keep carrying the old name, and no test, no build step, no reader reports it. The 8 that make noise are the ones embedded in an example; the example fails because it uses a name that no longer exists. What the single-term rule really saves is not the reader’s search, it is maintenance’s scan.

The version-5 measurement at the top says why this is urgent. The name surface changes at the fifth version; at that version, 45 claims are stale, 28 silently stale, and only 11 stay true. Renaming is the most frequent form of staleness, and the single-term rule brings it down to a job closeable with a single scan. Dual naming spreads the same job across double the surface and makes half of it invisible.

Summary

• When a style guide is written as a list of prohibitions, exceptions cannot be recognized and the rule cannot be argued about. A measurable item writes the rule’s name, what it measures, how it is measured, and where it falls.
• Dual naming opens three readings in the reader’s head — same thing, separate things, one is old — and the text does not say which is correct. Ambiguity spreads to the term: in the free regime, 52 claims are ambiguous.
• When the reader searches with the name they know, in the free regime they find 25 of 56 claims. Unifying the four most frequent terms raises found to 42 and lowers ambiguous to 19.
• Voice consistency brings the decision of whom the action falls to down from 56 sentences to one type choice; in the mixed regime, 28 of the claims are not written in their type’s voice.
• When a term is renamed, in the free regime the scan misses 31 claims and 23 of the missed are silent; the 8 that make noise are only the ones embedded in a runnable example.

Next Step

The last table surfaced a distinction, and it sits at the course’s center: 8 of the 31 missed claims made noise, 23 did not. The one thing the noisy ones shared was being embedded in a runnable example. The natural question, then, is this: how many of a document’s claims are actually embedded, and how far does silent staleness retreat if the embeddedness ratio is raised? The next lesson measures this ratio, defines what it means for an example to be runnable and complete, and holds its own example to the same standard.