Contents
“If the reader is to grasp what the writer means, the writer must understand what the reader needs.”
George Gopen and Judith Swan, “The Science of Scientific Writing”
While developing The Architecture of Nonfiction, I wrote this sentence:
Before
Software design named related failure modes with unusual precision because software makes the cost of structural mistakes painfully visible.
The sentence was grammatically sound. I knew exactly what related failure modes meant. The preceding discussion had covered clarity, cohesion, sequence, and audience awareness. The source notes connected those writing problems to coupling, dependencies, and interfaces. My working conversation with Codex, acting as my AI editor, contained the complete relationship.
The page did not.
During a review, I stopped on the phrase related failure modes. Did that phrase refer to the list in the previous sentence? The answer was yes, but the reader should not have needed to reconstruct that answer. The revision named the relationship:
After
Software design gave us precise language for the structural failures that make both code and writing difficult to understand and change: low cohesion, tight coupling, hidden dependencies, and unclear interfaces.
The original sentence worked inside the authoring environment because its dependencies were installed there. It failed when moved into the reader’s environment because the published text had not supplied them.
It was the writing equivalent of “works on my machine.”
Context Is Part of the Interface
Context is often treated as background: the history, definitions, examples, and explanatory material that surround the point. That description makes context sound optional or supplementary. Some of it is. The rest is part of the interface between the writer and the reader.
A technical component cannot perform its purpose unless its required inputs exist. A paragraph behaves similarly. It begins from information the reader must already have, establishes something new, and leaves the reader prepared for whatever follows. The Architecture of Nonfiction names those three parts as a paragraph contract:
Preconditions: What must the reader already know or accept?
Responsibility: What rhetorical purpose does the paragraph serve?
Postconditions: What information or reasoning must now be available to the reader and the following paragraph?
Context supplies the preconditions.
That does not mean every paragraph needs a miniature introduction. A precondition may have been established one sentence earlier, defined in the opening section, declared in an intended-audience statement, or supplied by knowledge the document can reasonably expect from its readers. The architectural requirement is availability. The context must exist where the intended reader can use it.
The phrase related failure modes violated that requirement. Its referent was available in my notes and working conversation, but the sentence exposed an interface that depended on private state.
The Given-New Contract Explains the Handoff
Writing scholarship identified this information handoff before I applied software terminology to it in The Architecture of Nonfiction. Herbert H. Clark and Susan E. Haviland’s Given-New Contract models an implicit agreement between a speaker and listener. Some information is presented as given, meaning the speaker believes the listener already knows or accepts it. Other information is presented as new.
The listener tries to connect the given information to an established and uniquely identifiable antecedent. In ordinary terms, the reader asks, “What established idea does this sentence expect the given information to connect to?” The reader then attaches the new information to that existing understanding.
Thomas Kent later applied the theory directly to paragraph construction. His “Paragraph Production and the Given-New Contract” describes the contract as a theory of information transfer that explains why unified and cohesive paragraphs matter. A paragraph does not feel coherent merely because every sentence concerns the same broad subject. Its sentences must connect established information to new information in a sequence the reader can follow.
When the required antecedent is missing, Clark and Haviland describe three detours a listener may take:
- Bridging: infer an unstated connection between the available information and the intended meaning.
- Addition: temporarily invent or assume the missing context so the sentence has something to connect to.
- Restructuring: reinterpret what the sentence treats as given and new until a workable relationship appears.
Those are recovery mechanisms, not free operations. The reader spends time resolving the writing instead of evaluating the idea. A successful guess can also hide the defect. The reader continues with an interpretation that feels plausible but may not be the one the writer intended.
Writers sometimes create that work deliberately. A story may introduce “the old woman” before explaining who she is. A persuasive essay may delay context to create tension or let the reader sit with a question. Clark and Haviland explicitly recognize that violations can produce useful implications and literary effects.
Technical explanation has less room for accidental suspense. If a deployment guide says “restart the service” before identifying the service, or an architecture decision says “this approach preserves consistency” without naming the approach or the kind of consistency, the reader is not experiencing artful delay. The reader is resolving an undeclared dependency.
Hidden Dependencies Have Different Shapes
Missing context does not always look like a missing definition. It often appears as a sentence that reads cleanly but requires the reader to supply one relationship the writer never made visible.
| Dependency | Reader question | Typical failure |
|---|---|---|
| Referential | What does this, that, it, or the example refer to? | The intended antecedent exists only in the writer’s working context |
| Terminological | What does this term or acronym mean here? | The author mistakes personal familiarity for shared knowledge |
| Argumentative | Which premise or prior conclusion makes this step follow? | The document skips a logical or causal connection |
| Situational | Under what conditions does this advice apply? | A context-specific decision reads like a universal prescription |
| Audience | What domain knowledge may this piece assume? | The document neither declares its prerequisites nor supplies them |
We encountered each shape while editing the parent essay. “Related failure modes” had an unclear referent. “Local request” used a neat-sounding phrase without defining what was local or who was making the request. A sentence about “the role that support must perform” compressed an argumentative relationship until the words no longer identified the actual job of the source, quotation, study, or example.
None of those problems required simpler ideas. They required explicit nouns and relationships.
The need for explicit nouns and relationships applies at larger levels too. An architecture document may describe a queueing decision without the throughput, ordering, or failure constraints that made the decision sensible. A proposal may recommend a reorganization without establishing which delivery problem the new structure addresses. An internal guide may begin with a procedure whose prerequisites were explained in a meeting that half its readers did not attend.
The writers know why the recommendation follows. Their memory completes the document every time they read it.
The reader receives only the document.
A Link Does Not Install Context
Another revision in the parent essay exposed a common web-writing failure. The draft referred to “the DITA specification” and linked to it. Readers who already knew DITA could continue. Everyone else had to follow the link, learn what DITA was, determine which part mattered, and then return to the argument.
The link made the dependency visible. It did not satisfy it.
The revised passage identifies OASIS DITA as an architecture for modular, reusable technical documentation. It then explains the relevant principle: a topic should be specific enough to address one subject or question and complete enough to make sense on its own. The reader can now understand why DITA appears in the argument without leaving the page. The link remains available for verification and deeper exploration.
This distinction applies to citations, internal links, documentation references, and phrases such as “as discussed above.” Required context belongs on the primary reading path. A link may provide evidence, detail, history, or another application. It should not contain the definition or premise the next sentence requires.
The rule is especially important for sources with impressive names. Mentioning a standard, framework, researcher, or book can create the appearance of support while asking the reader to discover the actual contribution. Name what the source provides. Then link it.
The Brain Dump Is the Opposite Failure
Once writers recognize context as a dependency, the obvious response is to supply more of it. Technical practitioners are particularly vulnerable to this move because we usually know more than the current reader needs. We know the system’s history, the alternatives the team rejected, the exceptions, the implementation details, and several related arguments that became visible during research.
Loading all of that material does not make the interface complete. It makes the interface indiscriminate.
Passing eight values to a method that needs three does not improve the method. It couples the caller to inputs the operation does not use. A document creates the same burden when every reader must process background that no later component depends upon.
OASIS DITA provides a useful boundary. A topic should be short enough to answer one question and long enough to make sense on its own. Specificity protects the topic’s purpose. Sufficiency protects the reader from missing prerequisites.
The correct amount of context is therefore not all available context. It is the smallest sufficient set for the intended reader and outcome.
Applying that standard requires the writer to separate three categories:
- Required context must appear before the component that depends on it.
- Helpful context may improve understanding but can be placed behind a link, footnote, appendix, or separate essay.
- Unused context may be accurate and interesting, but the current piece should not require the reader to process it.
The categories depend on purpose. A history of the SOLID acronym is required in an article about the principle’s origin, helpful in a broad introduction, and unused in a diagnostic checklist for readers who already know the framework. Context has no fixed importance outside the work it enables.
Every Independent Entry Point Is a Cold Start
A long-form essay or book can establish context cumulatively because its chapters provide an intended sequence. A standalone article cannot assume the same path. Readers may arrive through search, a direct link, a social post, a citation, or a recommendation from someone who supplied none of the preceding discussion.
Every independent entry point is a cold start.
This companion essay is an example. Its parent defines prose components, maps seven software principles to technical writing, and develops the complete paragraph-contract model. Requiring that essay first would make this companion incomplete. The local explanation of preconditions, responsibility, and postconditions supplies what this argument needs. The parent link remains available for readers who want the complete architecture.
Independence does require some repetition. The paragraph contract appears in both pieces because each reader interface depends on it. Copying the complete parent chapter would be wasteful. Omitting the model would leave this piece unable to perform its own purpose. The repeated definition is the cost of making the entry point usable.
Intended-audience statements solve a related problem. A piece does not need to teach every prerequisite if it clearly identifies what it assumes. The Architecture of Nonfiction, for example, tells readers that it expects familiarity with SOLID, DRY, YAGNI, interfaces, dependencies, and refactoring. It still revisits each principle where precision matters, but it does not retell the history of software design.
Declared prerequisites make the reader interface explicit. They tell readers which dependencies they must bring and allow the document to focus on the work it promised to do.
Readers and AI Fail Differently
Readers and AI collaborators share one constraint: neither can access context that remains only in the author’s head. Their failure modes differ.
A reader may slow down, reread the preceding paragraph, follow a link, search for a term, choose an interpretation, or abandon the piece. An AI system may ask a useful question or state an assumption that the author can correct. It may also generate a plausible substitute and continue as if the missing information had been supplied.
“Natural Language Is a Programming Language Now” develops the implementation risk. When an AI coding system converts an incomplete story or specification into working code, fabricated context can become behavior. The output may look complete because the model resolved the ambiguity instead of exposing it.
The remedy is still not to load everything. Large context windows make brain dumps possible, not useful. Irrelevant material competes with the standards, constraints, and decisions the current task actually requires. “Your AI Instructions File Should Be a Router, Not a Novel” gives that problem its own implementation pattern: keep universal rules available, route task-specific standards deliberately, and load examples when the task needs them.
For readers and AI, good context has the same three qualities. It is available before the work depends on it, relevant to the current responsibility, and authoritative enough to guide interpretation.
Run a Cold-Start Test
Authors are poorly positioned to detect their own hidden context because reading restores the intention that produced the words. The missing connection appears automatically. A useful review must recreate the reader’s environment instead of the author’s.
Use this cold-start test:
- State the intended reader and outcome. Identify what the reader should understand, evaluate, decide, or do.
- List the prerequisites. Name the domain knowledge, prior conclusions, definitions, and constraints the piece assumes. Mark whether each one is supplied by the piece, declared as knowledge the reader must bring, or absent.
- Inspect component openings. Check whether each section and paragraph begins from information the reader actually has.
- Trace every referent. Connect this, that, it, they, the example, the result, and similar phrases to one unmistakable antecedent.
- Verify each logical step. Ask which prior premise makes the conclusion follow and whether that premise appears in the document.
- Move required context onto the primary path. Explain enough for the reader to continue before offering a link or optional detail.
- Remove unused background. If no later component depends on the information, cut it or promote it into work with a purpose of its own.
- Review without the workbench. Give the publishable text, without notes, source conversations, or explanations from the author, to an editor, representative reader, or AI reviewer. Record every question that exposes a missing dependency.
An AI review can help if the model receives only the context the eventual reader will have. Ask it to identify undefined terms, ambiguous referents, undeclared prerequisites, and conclusions whose supporting premise is absent. Do not answer its questions during the audit. The questions are the evidence.
A human editor remains more valuable for the final judgment. The editor can distinguish a deliberate delay from an accidental omission, recognize when a domain assumption is fair for the audience, and tell you when the complete explanation still feels like too much.
Supply What the Reader Cannot Recover
Context does not make an argument correct. It makes the argument available for evaluation. A well-contextualized mistake is still a mistake, but the reader can now see the assumptions, inspect the reasoning, and identify where it fails.
That is why semantic specificity mattered throughout the parent essay. Replacing “related failure modes” with named structural problems did more than improve style. It removed a hidden dependency. Defining DITA before relying on its principle did more than help novices. It kept required context inside the reader’s interface.
The author will always know more than the page contains. Good writing does not erase that difference. It chooses which parts of that knowledge the reader must receive, which assumptions the reader may reasonably bring, and which details can remain outside the present work.
Your document does not fail because the reader lacks the contents of your head. It fails when the document depends on those contents and never supplies them.
Receipts
- The Given-New Contract: Herbert H. Clark and Susan E. Haviland’s “Comprehension and the Given-New Contract” describes the implicit agreement through which speakers distinguish established information from novel information. It also describes bridging, addition, and restructuring as ways listeners work around a missing direct antecedent. The software-dependency and “works on my machine” comparisons are mine.
- Paragraph cohesion: Thomas L. Kent’s “Paragraph Production and the Given-New Contract” applies the theory to unified and cohesive paragraph construction and treats the paragraph as a structure for effective information transfer.
- Reader expectations: George Gopen and Judith Swan’s “The Science of Scientific Writing” argues that successful technical communication depends on how readers interpret structural cues, not merely on whether the author placed accurate information on the page.
- Sufficient standalone context: The OASIS DITA specification’s definition of a topic supplies the balance used here: one bounded subject or question, developed with enough context to make sense on its own.
- First-party revision artifacts: The “related failure modes,” semantic-specificity, and DITA examples come from the documented review history of The Architecture of Nonfiction. They are examples from this project’s editorial process, not findings from the cited research.