The Architecture of Nonfiction

Intended Audience

This essay is for software engineers, engineering leaders, product practitioners, and other technical professionals who need to communicate ideas to other people. That writing may take the form of an article, newsletter, white paper, proposal, architecture document, or internal guide. The shared challenge is turning technically correct material into a coherent document another person can understand, evaluate, use, and revise.

It assumes that you recognize SOLID, DRY, YAGNI, interfaces, dependencies, and refactoring from software practice. Each chapter revisits the relevant principle where precision matters, but this is not an introduction to software design. That familiarity is part of the value: you can use mental models you already possess to inspect your writing.

1. Writing Has Architecture

“English is Just Another Programming Language.”

Andy Hunt and Dave Thomas, The Pragmatic Programmer

I had a draft about product ownership that made a sound argument. Product owners translate business needs into work developers can build. Teams that neglect the role pay for it in ambiguity, rework, missed commitments, and frustrated stakeholders. The sentences were clear. The examples were recognizable. The conclusion followed from the premise.

The draft was still not ready for publication.

Its strongest evidence was buried. A section about my own product ownership practice spent more time enumerating a tool pipeline than showing what changed for a real team. A later section tried to quantify the cost of poor requirements with hypothetical sprint math when I had direct experience that made the point better. The draft described product ownership as a high-leverage role, but its structure delayed the evidence that earned that conclusion.

No individual sentence exposed the problem. The document did.

The revision became “In Celebration of the Product Owner”. It retained the original premise, much of the original language, and several of the original sections. It also changed the path through the argument.

Architectural concern	Early draft	Revised article
Reader entry point	Began by asserting that the role was undervalued	Gave readers questions they could use to recognize the problem on their own teams
Evidence	Used a hypothetical calculation to estimate the cost of rework	Used an observed refinement increase from about three stories per hour to 13 to 15, plus the team’s record of 63 releases in 52 weeks
Author experience	Described a story development method largely through its tools and steps	Connected the method to a healthcare SaaS provider, the team’s constraints, and the results
Argument sequence	Moved from role definition to generalized costs and then advocacy	Moved from symptoms to causes, practice, results, downstream effects, and advocacy
Scope	Focused on the traditional product owner role	Added AI only after establishing the human craft that AI could help scale

This was not proofreading. It was not a grammar pass. The revision changed dependencies, moved evidence closer to the conclusions it supported, replaced a weak module, added missing context, and reordered the reader’s path.

It was an architectural revision of the entire article.

When Every Sentence Works and the Essay Does Not

Developers know this failure mode. Every method can be locally reasonable while the system remains difficult to understand. Every class can have a plausible name while responsibilities leak across boundaries. Every service can work in isolation while the complete request fails because one dependency was hidden.

Technical writing fails the same way. A sentence may be grammatical and accurate. A paragraph may contain useful information. A section may explain an important concept. Put them together in the wrong order, with the wrong boundaries, or in service of the wrong purpose, and the reader still has to reconstruct the system for you.

Writers are especially vulnerable because their drafts work on their machines. You know what an acronym means before you introduce it. You remember the example that made the conclusion obvious. You can see the connection between two sections because the missing transition already exists in your head. The reader receives only what reached the page.

A document is complete and correct only when two conditions are met: its statements must be true, clear, and mechanically sound; its parts must also compose into a useful whole.

The first condition is familiar and the work is essential. Check the facts. Attribute quotations and ideas accurately. Use terms consistently. Make each sentence say what you intend, then correct its grammar, spelling, punctuation, and usage. Style guides, dictionaries, automated checks, copy editors, and careful rereading all help find defects at this level. This work is also well covered by existing writing instruction and tools. This essay focuses on the second condition because mechanically sound statements do not automatically become a coherent document.

Software engineers already have a rich vocabulary for the coherence problem. We talk about cohesion, coupling, interfaces, dependencies, contracts, encapsulation, composition, and refactoring. We use principles such as SOLID, DRY, and YAGNI to reason about where responsibilities belong, how change should propagate, and which complexity has earned its place.

That discipline transfers to technical writing.

The Reader Is the Runtime

Code must satisfy a machine, but people must be able to understand and change it. A program can compile, pass its tests, and produce the correct result while remaining unnecessarily difficult to maintain. Martin Fowler states the distinction plainly in his argument for refactoring:

“Any damn fool can write code that a computer can understand, the trick is to write code that humans can understand.”

Martin Fowler, “Refactoring: Doing Design After the Program Runs”

Technical writing faces the human side of the same problem. The reader is where the document runs. Its individual statements can be grammatically valid while the document still demands too much context, conceals its central argument, repeats the same reasoning inconsistently, or makes one small update cascade through five unrelated sections. Sentence-level correctness does not rescue document-level failure.

This is why writing advice that stops at word choice and sentence mechanics often feels incomplete to technical practitioners. It can make the surface cleaner without changing the system underneath. The writing becomes easier to read line by line, but the reader still cannot tell why a section exists, what conclusion the evidence supports, or whether a long detour is part of the argument at all.

Good writing has architecture because readers experience more than sentences. They experience an ordered set of expectations. Each paragraph begins with context already available to the reader, adds or changes something in the reader’s understanding, and prepares the reader for what comes next.

Writing Was the Model First

Applying software principles to writing may sound like an attempt to borrow rigor from engineering. The history, however, runs in both directions.

Programmers have long described good code by comparing it to good writing. Robert C. Martin argues that code should read like well-written prose, with meaningful names, small components, separated concerns, and an order that respects the reader. Hunt and Thomas go further in The Pragmatic Programmer: treat English as another programming language and apply the same care to documentation that you apply to code.

The analogy works because software did not invent clarity, cohesion, sequence, or audience awareness. Good writing already contained them. 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. Software makes the cost of those failures painfully visible. Human reasoning can mask those failures in a document.

Those shared structural elements give us a useful reversal. If good prose has served as a model for readable code, the design vocabulary refined through software can help us inspect technical writing more deliberately.

This reversal also has precedent. Jacqui Read’s Communication Patterns applies architectural patterns and single responsibility to technical communication. Google’s technical writing guidance asks writers to treat paragraphs as independent units of logic with one topic. Rhetorical Structure Theory describes coherent text as a hierarchy of functional relationships such as evidence, elaboration, cause, and contrast. Across this prior art and scholarship, the vocabulary changes, but the observation remains the same: prose is composed from parts that have jobs and relationships.

The idea that writing has architecture is not new. It does not need to be. This essay synthesizes these ideas into a guide built around the mental models technical practitioners already possess. You do not need to learn a completely foreign taxonomy before you can diagnose a weak paragraph. You already know what hidden dependencies feel like. You already know why duplicated knowledge drifts. You already know that a component with three unrelated reasons to change will become difficult to maintain.

You already know how to manage complexity. Now bring that skill and discipline to your writing.

The Components of Prose

In this model, component is the umbrella term for any bounded structural part of a complete work. A document is the complete architectural container. In a long-form document, a chapter is a numbered major division, and a section is a titled division within a chapter. A shorter document may use sections without chapters. Paragraphs and sentences form the levels beneath them. When a principle applies across several levels, this essay uses component. When the level matters, it names the part directly.

Other terms describe form, state, or material rather than structural level. Piece refers to a complete work when its form or publication channel does not matter. Essay, article, post, white paper, and proposal identify particular forms or channels. A draft is an unfinished version. A passage is a bounded excerpt. Text is the actual wording or the primary written content.

The model examines five primary levels:

1. The document establishes a governing purpose and an intended reader outcome.
2. The chapter develops one major part of that purpose in a long-form document.
3. The section contributes one distinct part of the chapter’s argument or explanation. In a shorter document, it contributes directly to the document’s argument or explanation.
4. The paragraph serves one rhetorical purpose within the section.
5. The sentence contributes information, emphasis, emotion, rhythm, or movement to that purpose.

These levels are nested, but they are not interchangeable. A sentence can be excellent and still belong in the wrong paragraph. A paragraph can be coherent and still answer a question the section never needed to ask. A section can fulfill its own purpose while doing nothing for its chapter. A chapter can be valuable enough to become its own essay and still weaken the document that currently contains it.

We can inspect those components with familiar architectural concepts:

Concept	Writing question
Cohesion	Do the parts of this component serve the same rhetorical purpose and change for the same reason?
Coupling	How much must this passage know about, repeat, or coordinate with another passage?
Interface	What do the reader and surrounding text expect this component to provide?
Dependency	What context, definitions, evidence, or prior conclusions must exist for this passage to work?
Encapsulation	Which detail can stay behind a boundary until the reader needs it?
Composition	Do smaller units combine into a larger argument without losing their individual purposes?
Refactoring	Can the structure improve while the intended argument and reader outcome remain intact?

The vocabulary is not decoration. Each term gives us a diagnostic question that “Can this be clearer?” does not.

Clarity matters, but we usually judge it one sentence or paragraph at a time. An editor or AI system can make an awkward paragraph smoother without asking whether the paragraph belongs. It can strengthen a transition between two sections that should never have been coupled. It can compress a detailed explanation whose real problem is that the reader does not need it. The language of software architecture allows us to ask the larger question first: what job is this component supposed to perform?

A Paragraph Has a Contract

Well-crafted software components interact through contracts. The same is true of paragraphs. A paragraph assumes that the reader arrives with some context. It performs a rhetorical job. It leaves the reader knowing, believing, questioning, or expecting something new. We can state that contract directly:

Paragraph contract

Preconditions: What must the reader already know or accept?

Responsibility: What rhetorical purpose does this paragraph serve?

Postconditions: What should be true for the reader when the paragraph ends?

Consider the paragraph immediately before this callout. Its precondition is that the reader understands software components as units with defined contracts. Its responsibility is to apply that idea to a paragraph. Its postcondition is that the three-part model feels like a natural description of a paragraph rather than imported software jargon.

That contract does not dictate wording. The paragraph could be rewritten completely and still fulfill it. The new version might use a concrete example, a diagram, or a different rhythm. If it begins from the same context, performs the same responsibility, and leaves the reader prepared for the same next move, it remains a valid replacement.

We will return to that idea when we discuss substitution. For now, the important point is that prose components have behavior. Their boundaries define what the reader must already know, which parts of the component can change without breaking the surrounding argument, and what the next component may assume the reader now understands.

Natural Language Runs Things Now

Hunt and Thomas’s comparison between English and programming languages has become more literal in the age of AI. Prompts, specifications, agent instructions, and context files are forms of writing that cause software systems to act. Raw language has become an executable interface. The deeper implications deserve their own treatment, but the immediate lesson belongs here: ambiguity, hidden dependencies, conflicting instructions, and missing context are no longer only communication problems. At best, an agent asks more questions. At worst, a coding agent faithfully implements a bug that originated in the specification.

A Diagnostic Lens, Not a Law of Nature

Robert C. Martin assembled and popularized the five design principles now grouped as SOLID. Michael Feathers later gave the group its memorable acronym. Martin also explains in Clean Architecture that SOLID applies beyond traditional object-oriented classes to coupled groupings of functions and data. We are applying those principles to the structure and revision of technical nonfiction. Clearly, an essay is not literally a program. The analogy gives authors a diagnostic lens and a set of guidelines for improving their writing.

The distinction between rules and guidelines matters. Writers can violate an apparent rule for a legitimate rhetorical reason. Repetition can create rhythm, emphasis, or recall. A long sentence can carry several coordinated effects. The test is not whether prose resembles idealized code. The test is whether the analogy exposes a real problem for the reader.

The scope matters too. This framework applies most rigorously to technical and professional nonfiction whose primary job is to explain, instruct, analyze, or support a decision. In those forms, missing context, unstable terminology, weak evidence, and unnecessary detours interfere directly with the reader’s task.

Persuasive nonfiction needs more latitude. It may delay a conclusion, allow the reader to sit with a question before providing an answer, repeat an idea for emphasis, build emotional stakes, or use narrative to make an abstract contention matter. Those choices do not eliminate architecture. They change the component’s rhetorical purpose. A passage that looks inefficient as explanation may be essential to persuasion.

Persuasion still owes the reader factual integrity and coherent reasoning. It does not owe the reader the shortest path through every idea. Fiction has even wider latitude. It can preserve ambiguity, conceal dependencies, disrupt sequence, and break contracts for artistic effect. All bets are off when broken expectations and delayed gratification are the point.

The chapters that follow turn this model into a practical way to design and revise a document’s architecture. The principles will not do the writing for you. They will tell you where to look when every sentence seems fine and the document still does not work.

If writing has components, the first question is why each component should change.

2. Single Responsibility

“What is above all needed is to let the meaning choose the word, and not the other way about.”

George Orwell, “Politics and the English Language”

Single responsibility invites a simple interpretation: every component should do one thing. That is a useful warning against components that try to do everything. It is not a complete definition of the principle, and it is a poor rule for writing.

A strong sentence can make a point, elicit an emotion, raise a question, establish rhythm, and prepare the next move. A paragraph can explain a technical decision, show its consequences, acknowledge a limitation, and persuade the reader that the decision was sound. Reducing each component to one function would flatten writing that works precisely because it produces several effects at once.

Robert C. Martin defines Single Responsibility through change rather than activity:

“Gather together the things that change for the same reasons. Separate things that change for different reasons.”

Robert C. Martin, “SOLID Relevance”

That distinction gives us a better test for writing. A component can do several things when those things serve one rhetorical purpose and would be revised together. It has mixed responsibilities when part of it would need to change for a different audience, different evidence, different purpose, or different publication context while the rest should remain intact.

A sentence, paragraph, section, or chapter may do many things. Each should have only one reason to change.

Several Effects, One Purpose

The closing movement of the Gettysburg Address demonstrates the difference. Lincoln begins that movement by redirecting attention from the ceremony to the people listening:

“It is for us the living…”

Abraham Lincoln, Gettysburg Address

What follows performs several functions. Lincoln honors the people who died, assigns responsibility to those still alive, raises the emotional stakes of the unfinished work, and connects that work to the survival of democratic government. The passage commemorates, directs, persuades, and inspires.

Those are not four unrelated responsibilities. They serve one rhetorical purpose: moving the audience from remembrance to responsibility, and from responsibility to resolve. If that purpose changed, the emotional appeal, assignment of duty, treatment of sacrifice, and final statement about democracy would all need revision.

This is cohesion in prose. The parts of any component are cohesive when they contribute to the same rhetorical purpose and would need revision for the same reason. Within a paragraph, cohesion does not require every sentence to sound alike or perform the same function. It requires each sentence to contribute to that paragraph’s purpose.

One Topic Can Still Contain Several Responsibilities

Shared subject matter is not enough. A paragraph can stay on a single topic, such as a project, technology, or event, while mixing material that may need to change for unrelated reasons.

Constructed example: mixed responsibilities

Moving report generation to a background queue reduced request timeouts. The change should become our standard for long-running work, and the team should adopt smaller stories because the migration consumed most of the sprint. We also need to revisit the queue provider before its contract renews.

Every sentence concerns the same topic: the migration. The paragraph still has at least three responsibilities: justify an architectural pattern, recommend a delivery-process change, and raise a vendor-management decision.

Those responsibilities will not need revision at the same time or for the same reasons. New performance evidence could change the architectural recommendation without changing the story-sizing lesson. A revised team process could make the delivery advice obsolete while background processing remains appropriate. A new vendor contract could remove the procurement concern without affecting either technical conclusion.

Sentence-level editing would not resolve the paragraph’s mixed responsibilities. Separate them instead.

Constructed example: cohesive responsibility

Moving report generation to a background queue reduced request timeouts by removing long-running work from the request path. That result supports processing other operations asynchronously when they exceed the response-time limit.

The revised paragraph has one responsibility: connect an observed result to an architectural recommendation. Its two sentences perform different functions, but new information would require revising the evidence and recommendation together. The process lesson and vendor decision deserve their own paragraphs, another section, or no place in the piece at all.

Single responsibility is not a topic test. It is a change test.

Apply the Test at Every Level

The same principle operates at each level of the document:

Component	Single responsibility
Document	Advances one governing purpose for an intended reader
Chapter	Develops one major part of that purpose in a long-form document
Section	Contributes one distinct part of the argument or explanation developed by the chapter or shorter document
Paragraph	Serves one rhetorical purpose within the section
Sentence	Produces effects that would need revision for the same reason

These responsibilities nest. A sentence contributes to its paragraph. The paragraph advances its section. In a long-form document, the section advances its chapter, and the chapter develops part of the document’s purpose. A shorter document may omit the chapter level. A component can be internally cohesive and still belong in the wrong paragraph, section, chapter, or document. That is why a well-written paragraph can still need to move or disappear.

Purpose Before Phrasing

Orwell’s instruction to let meaning choose the word places intended meaning before phrasing. At the paragraph level, the same order applies: decide what the paragraph should accomplish before polishing its sentences. We do this with code: decide what the software should do, then write code that produces that behavior.

When you cannot state that purpose, awkward phrasing may be a symptom rather than the problem. The paragraph may contain two arguments that need separate treatment. It may combine evidence for one audience with advice for another. It may preserve an interesting detail that does not help the section fulfill its purpose. Rewriting the paragraph can clarify thought, but polishing cannot decide the paragraph’s purpose.

The Single Responsibility Principle gives revision a starting point: identify why the component should change, then keep together what changes for that reason and separate what does not.

Test a component by asking what would change if its audience, evidence, rhetorical purpose, or publication context changed. If its parts separate into groups that would change for different reasons, those groups probably represent separate responsibilities. If every effect would need revision for the same reason, the component is cohesive even when it performs several functions.

A component can be cohesive and still be difficult to extend. It may serve one purpose yet require extensive reconstruction whenever new evidence or examples arrive. The next question is whether the argument can accept new material without being rebuilt around it.

3. Open-Closed

“You should be able to extend the behavior of a system without having to modify that system.”

Robert C. Martin, “The Open Closed Principle”

The Open-Closed Principle may sound incompatible with writing. Drafts are revised constantly. An essay that is closed for modification is either finished, abandoned, or protected by an author who has stopped listening to evidence.

That objection comes from treating closed as a synonym for untouchable. Bertrand Meyer’s original definition described a closed module as one with a stable, well-defined description that other modules could use. The same module remained open when its capabilities could be extended. Martin later condensed the principle into the sentence above: new behavior should not require unnecessary changes to the working system around it.

A paragraph can be rewritten extensively without forcing the surrounding argument to change. In this analogy, closed describes the stability of the paragraph’s role and connections, not its wording. It still follows logically from the preceding context, serves the same rhetorical purpose, and establishes what the following paragraph needs.

The goal in software is not to freeze every line of code. It is to avoid changing code that remains correct merely because a new requirement has arrived. The equivalent goal in writing is to avoid rebuilding a sound argument every time you add a source, replace an example, address an objection, or apply the idea in another setting.

Stable Argument, Changeable Support

An essay contains parts that should become stable and parts that should remain easy to change. Its governing purpose, argumentative sequence, section responsibilities, and handoffs between sections form its stable structure. Sources, examples, counterarguments, applications, and publication-specific framing extend that structure and should remain easy to add, replace, or remove.

Stable structure	Available for extension
The question the essay resolves	Additional sources or evidence
The thesis that resolves it	A stronger or more current example
The sequence of questions the sections answer	A new counterargument or qualification
The responsibility of each section	An application in another field or setting
What each transition requires from the preceding section	Framing for a particular publication or audience

Stable does not mean sacred. It means the essay’s purpose, sequence, section responsibilities, and transitions are defined clearly enough that supporting material can change without forcing unrelated parts of the argument to change. You can replace a case study without discovering that the next three sections refer to its characters, chronology, and terminology. You can add a source without restating the thesis. You can acknowledge a new objection where objections belong instead of interrupting an unrelated example.

This separation is not present in every draft. Writers often discover the argument through the evidence, stories, and observations that prompted the piece. That is part of drafting. The Open-Closed test becomes useful once the argument has taken shape and you need to determine whether its structure can survive the next round of research and revision.

When One Example Becomes the Architecture

Consider an article about moving long-running operations out of the request path. Its first outline might grow directly from a successful migration:

Constructed outline: fragile argument

1. The Phoenix migration reduced request timeouts.
2. Because Phoenix worked, teams should use background queues for long-running operations.
3. Phoenix required new monitoring and retry logic.
4. The Phoenix results prove that asynchronous processing is worth the operational cost.

This hypothetical Phoenix migration does not merely support this outline. It supplies the structure, the transitions, and the conclusion. Replace Phoenix with a failed batch-email implementation or a study comparing several queue systems, and almost every section needs to be rewritten. The article is open to more Phoenix details, but it is not open to evidence that arrives in another form.

An extensible outline separates the general argument from the material used to test and support it:

Constructed outline: extensible argument

1. Governing contention: operations that regularly exceed the response-time limit should not remain in the request path.
2. Decision criteria: duration, retry behavior, consistency requirements, and user expectations.
3. Evidence: an observed migration or comparative study evaluated against those criteria.
4. Qualification: queues introduce monitoring, idempotency, retry, and operational costs.
5. Application: identify operations for which the benefits justify those costs.

The second outline can accept the Phoenix migration, a different case study, or several sources. A new failure mode belongs in the qualification. A new use case belongs in the application. The sections still have an order, but that order is determined by the reasoning the reader needs rather than the sequence in which the writer discovered the material.

The revised structure does not guarantee that every example will work. An example still has to provide the evidence its section requires. Open-Closed identifies where extensions can occur. The next principle will tell us what a valid replacement must preserve.

Create Deliberate Extension Points

An extension point in a document is a bounded place where a particular kind of material can be added or replaced without changing the responsibilities around it. It does not require a rigid template or empty sections reserved for every fact you might discover later.

In Boundaries Preserve Optionality, I describe good software boundaries as giving a system a place to change. A deliberate boundary in an article serves the same purpose. Within it, a source, example, counterargument, or application can change without pulling unrelated components into the revision.

You create useful extension points by stating the general assertion before its example, containing supporting material within a paragraph or subsection, and writing transitions around what that material establishes. A transition such as “These results support using queues when work exceeds the response-time limit” depends on the conclusion supported by the evidence. A transition such as “Phoenix proves queues are the answer” depends on the name and conclusion of one case.

The same method applies beyond evidence. Give counterarguments a defined place in the reasoning. Separate the explanation of a principle from its application to one industry. Keep a publication-specific introduction from becoming a premise that every later section must repeat. These boundaries let the document accept new material without allowing that material to take control of unrelated sections.

Do not create extension points for every change you can imagine. A technical essay does not need empty sections for future legal analysis, a classroom exercise, an executive summary, and an AI implementation merely because those additions are possible. Build around the variations your subject, evidence, and publication plans make plausible. YAGNI will give us a stricter test for the rest.

This Essay Is an Example

An essay can produce more ideas than its governing argument can contain. The paragraph-contract model could support a full treatment of unit tests for prose. The relationship between author context and AI behavior deserves its own piece. So does the question of when an interesting detail has accumulated enough reasoning and evidence to become another essay.

Those subjects do not need to disappear because they do not belong here. The technical cost of publishing another article or companion page is low, especially on the web. A supplemental piece can give an idea its own purpose, reader, and evidence without forcing the main essay to absorb scope it does not need.

A supplement should point readers back to the main essay for the foundation it extends. The main essay should remain complete without the supplement. That relationship gives interesting side paths somewhere to go while preserving the stable purpose and sequence of the primary piece.

Reality Can Require Modification

Open-Closed does not protect a thesis from contrary evidence. If a new source disproves the governing argument, contradicts a necessary premise, or reveals that the sections answer the wrong question, the structure must change. Preserving it would make the essay easier to extend and less true.

The distinction is between evidence that extends an argument and evidence that invalidates it. Another example of the same pattern may fit an existing section. A meaningful exception may require a qualification. Evidence that reverses the conclusion requires a new conclusion.

Do not declare a first-draft thesis closed and force every source to support it. A document is not structurally stable while you are still deciding what it says. Stability is earned through research, testing, and revision. Once the argument is sound, Open-Closed helps you keep unrelated additions from forcing unnecessary changes through the rest of the document.

A sound argument should be stable enough to accept new support and honest enough to change when that support proves it wrong.

Open-Closed gives replaceable material a defined place in the argument. It does not tell us whether a replacement fulfills the responsibility of that place. For that, we need to examine the contract between a paragraph, the paragraphs around it, and the reader.

4. Liskov Substitution

“…any property proved about supertype objects also holds for its subtype objects.”

Barbara Liskov and Jeannette Wing, “A Behavioral Notion of Subtyping”

If every dog is a mammal, then every husky and golden retriever must also be a mammal. That simple relationship captures the basic logic of substitution: properties guaranteed for the broader type must remain true for its subtypes. Paragraphs do not inherit from one another, but a revised paragraph can substitute for an earlier version. The final version may look entirely different, yet it must preserve the properties on which the surrounding paragraphs depend.

The analogy concerns behavioral substitution through a preserved reader contract, not inheritance.

A paragraph can be rewritten beyond recognition and still serve the same architectural role. Its sentences may change, its example may disappear, and its rhythm may improve. If the revision still fits between the same surrounding paragraphs and fulfills the same purpose, the argument can continue to use it.

We made such a revision in the previous chapter. The first version tried to explain stable and changeable parts through a metaphor:

Before

An essay contains parts that should become stable and parts that should remain easy to change. Its governing purpose, argumentative sequence, section responsibilities, and handoffs between sections form its spine, the literal backbone of the piece that remains stable. Sources, examples, counterarguments, applications, and publication-specific framing supply or extend the material around that spine. These should be easy to change.

The final version named the structure and the permitted changes directly:

After

An essay contains parts that should become stable and parts that should remain easy to change. Its governing purpose, argumentative sequence, section responsibilities, and handoffs between sections form its stable structure. Sources, examples, counterarguments, applications, and publication-specific framing extend that structure and should remain easy to add, replace, or remove.

The revision removed the spine metaphor, eliminated the unclear reference in “These,” and defined what easy change means. It did not change the paragraph’s place in the argument. The preceding paragraphs still establish that architectural closure concerns a paragraph’s role rather than its wording. The table that follows can still itemize stable structure and available extensions. The replacement changed the implementation while preserving what the surrounding paragraphs required.

That is the useful prose interpretation of the Liskov Substitution Principle.

Replacement Depends on Behavior

Liskov and Wing define subtyping through preserved properties and observable behavior. A valid subtype must continue to behave as users of its supertype expect. Martin translates the principle into a direct test:

“A program that uses an interface must not be confused by an implementation of that interface.”

Robert C. Martin, “SOLID Relevance”

The principle is not limited to class inheritance. It asks whether a replacement preserves the behavior on which its consumers depend. In this chapter’s paragraph-level model, the preceding paragraph supplies context, the reader interprets the replacement using that context, and the following paragraph depends on what the replacement establishes.

Topic similarity is not enough. Two paragraphs may discuss the same queue migration, management decision, or research result while performing different rhetorical work. A replacement is valid only when it uses the context already established, fulfills the required purpose, and supplies the reasoning or information that the following paragraph needs.

The Paragraph Contract

We can describe those requirements through three questions:

Contract element	Writing question	Software parallel
Preconditions	What must the reader already know, accept, or be considering for the paragraph to make sense?	Inputs, assumptions, required context, and initialization
Responsibility	What must the paragraph establish, challenge, connect, clarify, or demonstrate?	Required behavior or logic
Postconditions	What information or reasoning must now be available to the reader and the following paragraph?	Output, side effect, or dependable resulting condition

The contract does not guarantee a particular reaction from every reader. A persuasive paragraph cannot ensure agreement, and an explanation cannot ensure comprehension. The postcondition identifies what the paragraph must make available: evidence for a conclusion, a distinction the following paragraph uses, a question the reader can now evaluate, or context required for the next example.

The revised Chapter 3 paragraph that distinguishes stable structure from changeable support has a compact contract:

Preconditions: The reader understands that architectural closure applies to a paragraph’s role, not its exact wording.

Responsibility: Distinguish the parts of an essay that should stabilize from the supporting material that should remain easy to change.

Postconditions: The reader can interpret the table that separates stable structure from material available for extension.

The first and final versions both satisfy that contract. Their wording differs because the revision improved precision. Their architectural role remains the same because the surrounding argument can depend on the same result.

The Transition Makes the Interface Visible

In ordinary writing language, readers often experience a paragraph’s interface as its transition. The two are related, but they are not identical. The interface is the contract that governs the connection. The transition is the wording or logical progression that makes the connection visible.

A phrase such as “the first category” signals that a prior paragraph must have established at least two categories. “However” tells the reader that the new sentence will qualify or oppose what came before. A paragraph that begins with “That failure has three causes” depends on a failure already being defined. These transitions expose preconditions. They tell us what the new paragraph expects to find.

The contract also defines what the paragraph must establish before it ends. The following paragraph may depend on a distinction, conclusion, question, or piece of context introduced there. A polished transition cannot repair the contract when that information is missing. It can only make the absence less obvious on a quick read.

Thomas Kent’s Given-New Contract describes paragraph cohesion as information transfer. New information must connect to information already available to the reader. Herbert Clark and Susan Haviland’s earlier work explains the reader’s side of that process: people distinguish information they can infer from shared context from information being introduced for the first time. The software vocabulary is our addition. The requirement to connect new information to established context comes from writing scholarship.

This is why missing context produces a prose version of “works on my machine.” The paragraph makes sense inside the author’s head because the required information is present there. It fails for the reader because the document never supplied that precondition.

The Same Topic Can Still Break the Contract

Replace that stable-structure paragraph with this one:

Invalid substitute

Essays change during drafting. Writers add sources, rework examples, change titles, and reorganize sections as research deepens. Revision is recursive, and no outline survives every new discovery.

The substitute is accurate and relevant to the chapter’s topic. It may even be a useful paragraph elsewhere. It is invalid in this position because it never distinguishes stable structure from changeable support. The table that follows now appears without the distinction it itemizes, and the next paragraph’s opening, “Stable does not mean sacred,” refers to an idea the replacement did not establish.

The failure is architectural rather than grammatical. Editing the substitute for clarity will not make it valid. It needs a different purpose, a different position, or additional material that fulfills the original contract.

A Compact Unit-Test Parallel

The three-part contract resembles the setup, exercise, and check performed by a unit test:

• Arrange the preconditions: Supply the context the paragraph requires.
• Exercise the responsibility: Let the paragraph perform its assigned rhetorical work.
• Check the postconditions: Confirm that the following paragraph can proceed without an unstated assumption.

The parallel is useful because it turns a general impression about flow into something an author or editor can inspect. It is also limited. Readers are not deterministic systems, and written language does not produce a perfectly measurable state. The deeper comparison belongs in the supplemental piece on unit tests for prose.

Test the Substitution

This contract gives structural revision a precise test. An editor can replace awkward phrasing, choose a stronger example, split one paragraph into two, or rebuild the paragraph completely. The substitution remains valid when the revised material accepts the same context, fulfills the same purpose, and establishes what the surrounding argument needs.

A paragraph can satisfy that contract and still expose the reader to terminology, background, or detail that the reader does not need. The next principle shifts attention from compatibility between paragraphs to the interface presented to a particular audience.

5. Interface Segregation

“Each business rule defines an interface for just the data access facility that it needs.”

Robert C. Martin, “A Little Architecture”

The previous chapter examined the interface between paragraphs. The Interface Segregation Principle asks a different question: what should the document present to this reader for this task?

Technical writers often know more than any one reader needs. We know the history that led to the decision, the alternatives that failed, the implementation details, the exceptions, the relevant research, and several adjacent ideas worth exploring. Putting all of that knowledge into one document can feel thorough. We call it a brain dump: supplying every piece of context the writer has instead of the context the reader needs.

In software, that resembles passing eight values to a method that uses only three. The unused inputs make the interface harder to understand and force every caller to provide data the method does not need. A brain dump creates the same burden for the reader.

In software, Martin summarizes the problem as keeping interfaces small enough that users do not depend on capabilities they never use. The writing equivalent is not simply “write less.” It is to require the reader to consume only the context, reasoning, and detail necessary for the reader’s purpose.

This essay uses that reader interface. It assumes familiarity with Robert C. Martin, general software design principles, and common terms such as method, interface, dependency, and refactoring. It still defines each SOLID principle because the writing interpretation depends on its precise meaning. It does not recount the history of Clean Code, survey the development of software engineering, or profile important figures in the field because that background is not required to apply the framework.

The Reader Owns the Interface

Martin illustrates the principle with a business rule that needs data from a database. The business rule is the consumer. It accesses the database through a gateway interface that includes only the operations the rule uses. Another business rule may require different operations and therefore defines a different gateway interface. The database can provide many more capabilities, but those capabilities do not become part of a business rule’s interface merely because they exist.

The same person can require different writing interfaces at different moments. A developer learning an unfamiliar system needs an explanation. That developer implementing a known change needs a procedure. During an outage, the same developer may need a concise reference. Combining all three into one uninterrupted path makes each task harder.

The Diátaxis framework organizes technical documentation around four distinct reader needs: tutorials, how-to guides, reference, and explanation. The categories matter here because they are organized around what the reader is trying to accomplish, not around everything the writer knows about the product.

For an author, interface segregation begins with the intended reader outcome. The author must decide what the reader should understand, evaluate, decide, or be able to do after reading. That outcome is the intended output of the piece. It does not guarantee comprehension, agreement, or action, but it determines what the interface must provide.

That gives us two questions before we decide what belongs:

• Who is the intended reader?
• What should the piece enable that reader to understand, evaluate, decide, or do?

Demographics alone are insufficient. “Software engineer” identifies a broad audience, not a task. A software engineer evaluating an architectural argument needs a different interface from one implementing the architecture or troubleshooting it in production.

One Idea, Three Interfaces

My published treatment of “Stop Reading AI Code. Score It.” provides a concrete example. It argues that an agent can apply a code-quality rubric, while the human remains responsible for verifying outcomes. The idea appeared through three interfaces.

The LinkedIn version gave a feed reader the reframe, one result, and the implication:

LinkedIn interface

The interesting question was never read or measure. It was human or agent.

Once you accept that the reviewer does not have to be you, the rest falls out. Deterministic where measurement works. An agent applying anchors where it does not. An outcome check the human still owns.

The full blog post gave a skeptical technical reader the governing argument, rubric design, counterarguments, limitations, and current implementation status. Its central reframe received more explanation:

Article interface

Reading code was never the goal. The goal was a confident answer to two questions: is this clean, and does it work. Reading was the cheapest tool we had to answer them. It is no longer the cheapest tool, and for AI-generated code it is no longer even a good tool.

Readers who wanted to inspect or adapt the scoring system needed still more detail. The post moved that implementation material into an appendix and marked the boundary explicitly:

Implementation interface

Skip this section if you trust the rubric and just want the argument. Read it if you want the receipts.

The LinkedIn post would fail its feed-reader task if it tried to include nine scoring dimensions, calibration thresholds, and metric formulas. The article would fail its evaluative task if it offered only the feed-sized reframe and asked a skeptical reader to accept the conclusion without the reasoning. The appendix would fail as an implementation reference if it omitted the anchors and calculations to preserve the article’s pace.

These interfaces differ by more than length. They serve different tasks for different readers. The reader scanning their LinkedIn feed decides whether the idea deserves attention. The article reader evaluates the argument. The implementation reader inspects or adapts the method.

Move Optional Detail Off the Primary Path

Appendices, footnotes, links, sidebars, and supplemental pieces allow a document to serve more than one reader without making every reader follow the same path. They work when the primary text remains complete for its intended task and the optional material serves a distinct additional need.

A footnote can define an unfamiliar term for readers who need it while allowing experienced readers to continue. A sidebar can hold historical context that enriches an explanation without becoming a prerequisite. An appendix can expose calculations to readers who want to reproduce the method. A link can lead to a full implementation or explanation without requiring the current piece to teach it. The link to Diátaxis gives readers a path to the complete framework while this essay provides the context required for its immediate point.

Together, these tools create progressive disclosure. The primary text presents the information required for its reader task, while optional paths reveal more detail when another task requires it. This is a practical form of encapsulation: the additional detail remains available without becoming part of every reader’s interface.

Optional detail must actually be optional. If the conclusion depends on a definition hidden in a footnote, the primary interface is incomplete. If the main text tells the reader to follow three links before the next paragraph will make sense, the document has forced the reader to retrieve required context elsewhere instead of supplying it.

Citations require a separate distinction. A citation may appear in a footnote, but its format does not make the evidence optional. Citations declare the relationship between an assertion and its source. That dependency belongs primarily in Chapter 6. Here, the footnote matters only as a way to keep optional explanation off the primary reading path.

Change the Interface with the Channel

The publication channel changes what the reader can reasonably expect and what the document must provide.

Form	Intended reader outcome	Required interface
Long-form essay	Understand and evaluate the cumulative argument	Full sequence, definitions, evidence, qualifications, and transitions
Standalone blog post	Understand one principle without reading the long-form essay first	Necessary premise, focused argument, independent examples, and a complete conclusion
LinkedIn post	Recognize and evaluate one compressed insight in a feed	Immediate context, central reframe, enough support to make it credible, and a clear implication
White paper	Evaluate a technical position or method rigorously	Methodology, evidence, limitations, citations, and enough implementation detail to assess the work
Reference or appendix	Retrieve facts or reproduce a method	Definitions, parameters, steps, tables, and navigation optimized for lookup

The long-form essay can depend on sequence because the chapters form one reading path. A derived blog post cannot assume that its reader completed the earlier chapters. It must supply its own required context. A LinkedIn post should not compress the whole essay until every sentence becomes a summary. It should expose one useful insight and let the larger work serve readers who need the complete argument.

The OASIS DITA standard provides an architecture for modular, reusable technical documentation. It defines a topic as short enough to address one subject or question but long enough to make sense on its own. That balance applies beyond documentation. Independence requires sufficient context, not exhaustive context.

Small Enough, but Still Complete

Interface segregation has two failure modes. An oversized interface forces the reader through terminology, history, caveats, and implementation detail that the task does not require. An undersized interface omits the context, evidence, or definitions required to understand the piece.

Chapter 4 used “works on my machine” to describe missing reader context. The document makes sense to the author because every prerequisite is already present in the author’s memory. Interface segregation does not solve that problem by removing even more. It asks for the smallest reader-facing interface that remains sufficient for the task.

Smaller is not automatically simpler. A compressed explanation can make the reader stop, search for a definition, infer a missing premise, or ask the author what a sentence means. The document is shorter, but the reader performs more work. A good interface minimizes irrelevant material without transferring required work to the reader.

This is also why technical and persuasive nonfiction may expose different interfaces. Technical explanation usually benefits from explicit prerequisites, definitions, and decision rules. Persuasion may delay part of the reasoning, build emotional context, or let the reader sit with a question. The interface still needs to supply what that rhetorical purpose requires.

Interface Segregation Is Not Dependency Inversion

The two principles can appear to address the same details, but they ask different questions:

Principle	Governing question	Concern
Interface Segregation	What must this reader consume for this task?	The reader-facing surface of the piece
Dependency Inversion	What role does this detail play in the argument, and what higher-level idea governs it?	The internal relationship between the argument and its support

Interface Segregation may move an implementation example into an appendix because most readers do not need it. Dependency Inversion asks whether that example supports the governing argument, has started controlling the argument, or belongs to another argument entirely. Interface Segregation determines what the reader must encounter. Dependency Inversion determines how each detail relates to the argument.

A useful reader interface presents enough for this reader to complete this task without requiring knowledge that belongs somewhere else.

Once the reader-facing interface is bounded, the next question concerns the reasoning behind it. Does the governing argument determine which details appear, or have the details begun to determine the argument?

6. Dependency Inversion

“Source code dependencies always point inwards.”

Robert C. Martin, “The Clean Architecture”

Dependency Inversion is one of the harder SOLID principles to apply to an argument without distorting it. In software, the principle prevents high-level policy from being shaped by low-level implementation details. In writing, the governing argument should likewise determine what kinds of support it needs and where that support belongs.

The argument does not outrank the evidence. A source, study, or example may expose a weakness in the thesis and force the writer to qualify, revise, or abandon it. The argument controls how the evidence is organized. The evidence controls what the argument is allowed to conclude.

That distinction matters because writers often discover an argument through the material they collect. A study exposes a pattern. An anecdote raises a question. A quotation gives language to an intuition. Discovery can begin with detail, but the finished essay should not preserve the order in which the author happened to find things.

Point the Structure Toward the Argument

Martin’s “The Clean Architecture” separates high-level policies from mechanisms such as databases, frameworks, and user interfaces. The policies sit toward the center. The implementation details sit outside them. Source dependencies point inward so the central policy does not become organized around one particular mechanism.

The writing parallel does not require a set of concentric circles. It requires separating the argument the author seeks to make from the particular material used to develop, support, or test that argument.

Software architecture	Argument architecture
High-level policy	Governing question and thesis
Stable abstraction	What the argument needs from the material: a definition, example, evidence, counterargument, qualification, or application
Low-level detail	Sources, quotations, anecdotes, studies, and examples

Open-Closed and Dependency Inversion both discuss replaceable support, but they ask different questions. Open-Closed asks whether a new source or example can occupy a bounded place without forcing unrelated sections to change. Dependency Inversion asks which direction governs the relationship: the argument defines the role the support must perform, while the evidence limits what the argument may conclude.

Chapter 1 argues that a document may need architectural revision even when its individual sentences are clear. That argument needs an example showing structural change rather than sentence-level correction. The before-and-after history of “In Celebration of the Product Owner” provides that evidence. A documented before-and-after example from another piece could replace it without changing what Chapter 1 needs to establish.

This resembles depending on an abstraction because the essay identifies what it needs before selecting the material that will provide it. Once that need is explicit, a source, quotation, study, anecdote, or example can be evaluated by whether it satisfies the requirement.

The mapping has a limit. A software policy can remain valid while one database is exchanged for another. An assertion about the world cannot remain valid when its supporting evidence fails. If the retained product-owner records had shown no improvement in refinement or release cadence, they could not fill the same evidentiary role while leaving the opening conclusion untouched. The argument would need qualification or a different conclusion. The architectural role may remain stable, but the thesis must still reflect what the available evidence supports.

Let the Governing Point Organize the Support

Barbara Minto’s Pyramid Principle is a business-writing framework that begins with a governing point and organizes supporting ideas beneath it. The supporting ideas answer questions raised by the point, and the details beneath them develop those answers. The framework gives writing its own precedent for the direction Dependency Inversion describes: the higher-level reasoning determines what support the document requires.

Without that direction, research can become the outline. A writer who collected Martin, Meyer, Liskov, Minto, and several composition studies might create one section for each source. The resulting essay would reproduce the research process. It would not necessarily help the reader diagnose and revise the architecture of technical writing.

This essay is organized by the problems its audience needs to solve instead. Meyer helps distinguish stability from immutability in Chapter 3. Liskov and Wing provide the behavioral basis for replacement in Chapter 4. Minto belongs here because her framework shows how a governing point organizes its support. The authors do not receive sections merely because their work was collected. Each source appears where it performs a defined role in the argument.

Before drafting, we assigned sources to specific argumentative needs:

Argumentative need	Sources assigned to it	Role in the essay
Establish that good writing has architecture	Rhetorical Structure Theory, Minto, Information Mapping, DITA, and Diátaxis	Rhetorical Structure Theory models functional relationships among parts. Minto organizes support beneath a governing point. Information Mapping structures reusable information modules around a clear purpose. DITA defines modular topics that remain independently understandable. Diátaxis organizes documentation around distinct reader needs.
Establish direct precedent for transferring software principles to communication	Jacqui Read, Google Technical Writing, and Hunt and Thomas	Show that the transfer has already been made in narrower forms
Define a paragraph contract	Kent’s Given-New Contract, Clark and Haviland’s reader-context research, and Liskov and Wing	Connect prior context, rhetorical responsibility, and dependable results
Distinguish structural revision from surface correction	Nancy Sommers and Martin Fowler	Connect structural revision in writing with refactoring of code

We collected more material than this essay would use. Collection earned each source consideration, not publication. The argument still decides whether the source is required, what question it helps answer, and how much space it receives.

A Citation Declares a Dependency

A citation is not a decorative receipt. It identifies which source a factual assertion, definition, or interpretation depends upon. Its placement should make that relationship easy to inspect.

In a web essay like this one, a link attached to the relevant source or statement serves as the citation. The sentence around that link must explain what the source contributes. The link enables verification and further reading, but it does not perform the explanation.

The final Receipts section consolidates those sources for review. It does not replace the local links that make individual dependencies visible.

Footnotes and citations can share the same typographic form while serving different roles. A footnote may move optional explanation off the primary reading path. A citation records an evidentiary dependency whether it appears inline, in a footnote, or in a consolidated source list.

Keep Useful Detail in Its Proper Role

An interesting detail can behave like a good code comment. It may explain why a decision was made, preserve context that would otherwise disappear, identify a constraint, or make the surrounding logic easier to understand. Its subordinate position does not make it trivial. Some comments preserve the reason the code is correct, and some details preserve the reason an argument is credible.

The analogy concerns role, not importance. A comment should not become a restatement of the code it describes. In the same way, a detail should not quietly introduce a second thesis that the surrounding essay has no room to develop.

Several ideas in this project crossed that boundary. The resemblance between paragraph contracts and unit tests is useful, but a complete treatment would require its own examples and limitations. The effect of author-specific style guides on AI output raises a separate question that this essay cannot resolve in passing. The real-time record of how this essay was researched and revised has become its own behind-the-scenes piece.

We did not discard those ideas. We promoted them to the supplemental queue, where each can receive its own context, evidence, examples, and conclusion. Their removal makes the present essay more complete because they no longer interrupt responsibilities that belong to other chapters.

Use a simple decision table when a detail begins competing with the argument:

Material	Required here?	Needs its own treatment?	Decision
Core evidence	Yes	No	Keep in the essay
Clarifying example	Yes	No	Keep in a bounded place
Interesting adjacent argument	No	Yes	Promote to a supplement
Attractive fact with no reader benefit	No	No	Cut

A detail that keeps trying to take over the essay is asking to be the topic of a different essay.

Promotion is not the right answer for every difficult detail. Sometimes the governing argument is wrong. Sometimes the source exposes a missing premise or a contradiction that requires structural revision. Moving inconvenient evidence to a supplement would conceal the failure rather than correct it.

Research Can Change the Architecture

Dependency Inversion becomes dangerous when a writer mistakes control over the essay’s organization for control over the results of the research. Honest research is not a service that returns whatever conclusion the thesis requested. It can change the question, split one section into two, remove a confident assertion, or overturn the entire premise.

The sequence therefore changes across the writing process. During discovery, evidence may lead. The writer follows sources, examples, and contradictions until the real problem becomes clear. During composition, the emerging argument assigns that material a place and a responsibility. During revision, new evidence tests both the details and the structure built above them.

This is not inconsistency. It is the feedback loop that keeps the architecture honest. Evidence can reshape the argument during research, and the revised argument can then give that evidence an intelligible order.

An argument should control the arrangement of its details without controlling their verdict. Once those relationships are explicit, another maintenance problem becomes visible: the same knowledge or intent can appear in several places and begin changing independently.

7. DRY

“Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.”

Andy Hunt and Dave Thomas, The Pragmatic Programmer

DRY may be the software principle most likely to become a bad editing command. Its name seems to tell writers to search for repeated words, sentences, or ideas and remove them. Applied literally, that instruction would eliminate useful emphasis, flatten rhythm, and force readers to retrieve context that the document should provide.

Hunt and Thomas define something more specific. In their clarification of the principle, they write, “DRY is about the duplication of knowledge, of intent.” Matching text can represent different knowledge, while different wording can represent the same knowledge. The maintenance problem begins when the same fact, definition, instruction, or decision is expressed in several places that can change independently.

The useful test is change. If one fact changes, how many passages must the writer find and update? If one definition becomes more precise, how many older versions can remain in circulation? If two passages disagree, can the writer and reader tell which one governs?

For writers, a playful rename makes the distinction clearer:

Don’t repeat your knowledge, even when you change the words.

DRY is not a ban on repetition. It is a test for competing sources of truth.

Different Words Can Duplicate the Same Knowledge

Imagine that the long-form essay, a future standalone post, and the eventual review checklist each define Single Responsibility without referring to the maintained source notes:

Location	Independently maintained definition
Long-form essay	A paragraph should have one reason to change.
Standalone post	A paragraph should do one job.
Review checklist	A paragraph should contain one main idea.

The three statements contain little repeated wording. They still represent the same concept three times, and they define three different tests. A paragraph can use several techniques in service of one purpose, contain several related ideas, and still have one reason to change. It would pass the first test and could fail the other two.

Revision makes the problem worse. Suppose the author clarifies that audience, evidence, purpose, and publication context can create different reasons for change. The essay receives the revision. The standalone post keeps “one job,” and the checklist keeps “one main idea.” The content system now teaches three versions of Single Responsibility depending on where the reader enters it. In a longer work, such as a book, the same drift can occur inside a single publication when a definition changes from one chapter to another.

This is the prose version of duplicated knowledge. The failure is not that a sentence appeared twice. The failure is that the definition is maintained independently in several passages.

One Definition, Several Expressions

This project keeps the complete interpretation of Single Responsibility in the source dossier. The outline translates it into a drafting constraint, and the essay translates it into a reader-facing explanation:

Artifact	Expression	Responsibility
Source dossier	SRP means one reason to change, not one function. Several effects may serve the same rhetorical purpose and change together.	Maintain the complete interpretation and its caution.
Essay outline	Replace the weak “do one thing” interpretation with Martin’s “one reason to change.”	Constrain what Chapter 2 must teach.
Long-form essay	“A sentence, paragraph, section, or chapter may do many things. Each should have only one reason to change.”	Give the reader a concise, usable expression of the principle.

These expressions are not identical because they serve different purposes. They remain consistent because they derive from the same maintained interpretation. If later research changes that interpretation, the dossier changes first. The outline and published text must then be reviewed against it.

A source of truth does not require one sentence to appear everywhere. It requires one maintained meaning against which every local expression can be checked.

Repetition Can Perform Useful Work

Chapter 1 uses deliberate repetition to describe a structural software failure:

Every method can be locally reasonable while the system remains difficult to understand. Every class can have a plausible name while responsibilities leak across boundaries. Every service can work in isolation while the complete request fails because one dependency was hidden.

“Every” and “while” repeat. The sentence structure repeats. The knowledge does not. Each sentence names a different level of the system and a different way local correctness can fail to produce a correct whole. The repeated structure creates rhythm, connects the examples, and builds from method to class to service.

Removing the repetition would not make the paragraph more maintainable. It would remove part of the paragraph’s rhetorical technique.

Repetition can serve several legitimate purposes:

• Emphasis: Returning to a central idea tells the reader that it matters.
• Rhythm: Repeated syntax can make a sequence easier to follow and remember.
• Recall: Restating an earlier result can restore it when a later section depends on it.
• Parallel evidence: Examples from different fields can repeat the same relationship while demonstrating that the principle applies beyond one context.
• Independent entry points: A standalone piece may need context that already exists elsewhere because its reader did not arrive through the earlier piece.
• Audience and channel: A white paper, blog post, and LinkedIn post may express the same knowledge differently because their readers need different interfaces.

The question is not whether something repeats. The question is what the repetition does and who is responsible for keeping the repeated idea consistent.

A Standalone Piece Must Supply Its Own Context

The Write the Docs documentation principles use the term ARID: Accept (some) Repetition In Documentation. Documentation must sometimes restate knowledge from the software it describes. Strictly removing that repetition would leave readers without the information they opened the documentation to find.

The same requirement applies to the nine posts derived from this essay. The DRY post cannot assume that its reader completed Chapters 1 through 6. It must restate the premise that prose has architecture, define the relevant software principle, and supply enough context for the writing interpretation to stand on its own.

A link to the long-form essay cannot replace that context. The link gives the reader a path to more detail. It should not require the reader to leave one unfinished explanation and retrieve its premises from another page.

Strictly speaking, the standalone post creates another representation of shared knowledge. The practical response is not to omit it. The response is to make the repetition deliberate, identify the maintained source, and review the local expression whenever that source changes.

This distinction also applies across channels. The long-form essay may explain a principle through several sections and examples. A LinkedIn post may state one reframe and one implication. A white paper may need the definition, evidence, limitations, and method. Each expression can differ without becoming a competing source of truth when the underlying knowledge remains consistent.

Maintain Knowledge, Not Matching Strings

A content system needs explicit ownership for the material most likely to drift:

• Definitions of the principles and the limits of each analogy.
• Exact quotations, source details, and attribution notes.
• Factual assertions, measurements, dates, and version-specific information.
• The governing premise and intended audience of a related series.
• Style and terminology decisions that should remain consistent across publications.

The authoritative representation may live in a research dossier, specification, glossary, data file, style guide, or another maintained artifact. The format matters less than the responsibility. Writers and editors must know where a change begins and which published expressions depend on it.

Not every repeated sentence needs to become a variable, include, or content block designed for hypothetical reuse. That response can make a passage harder to read and edit. It can also erase useful differences between audiences and publication contexts. Centralize the knowledge that must remain consistent. Let each piece express that knowledge in the form its reader needs.

Repeated language can strengthen a piece. Independently maintained knowledge weakens it. Once writers begin preventing future duplication, however, they can be tempted to create reusable abstractions, explanations, and content modules before any reader needs them. That is where YAGNI becomes the next diagnostic.

8. YAGNI

“YAGNI is a meditation on timing.”

Kent Beck, “The Cost YAGNI Was Never About”

YAGNI, short for “You Aren’t Gonna Need It,” is often reduced to an instruction to write less. Cut the long explanation. Remove the background. Delete the footnote. Get to the point. Sometimes those are the right edits. They are not the principle.

Beck describes YAGNI as a decision about when to build structure. If the present work needs the structure, build it. If a future requirement might need it, wait until that requirement arrives and reveals what the structure must do. Building too soon commits the work to assumptions that may prove wrong even when the predicted need eventually appears.

That timing decision is ultimately a test of present value. Extraneous code and gold-plated features consume development and maintenance effort without satisfying a current business need. Extra information behaves the same way. It consumes the reader’s time and attention, but it does not create value merely by being accurate, interesting, or related to the subject.

More information creates more reading. It does not automatically create more value. Material earns its place when it helps the intended reader understand, evaluate, decide, or act. If it does not improve one of those outcomes, the writer should remove it, defer it, or develop it in a piece with a purpose of its own.

YAGNI responds to a familiar engineering habit: building a more general or complicated solution for requirements expected in the future. Writers can over-engineer an essay in the same way. We add another example in case the first one does not persuade every reader, an aside for a question someone might ask, background for an audience the piece does not address, or related research that might become useful later. Each addition is connected to the subject. None necessarily reinforces the essay’s present purpose.

Planning for future use is not the problem. Implementing that future inside the current piece is. Source notes and the supplemental queue preserve possible extensions without forcing the current reader through material intended for another argument.

The prose version asks whether the current argument and target audience require the material now. A section may be intelligent, accurate, and related to the general subject while doing no work for the argument the essay actually makes. Related to the topic is not the same as required by the argument. YAGNI identifies speculative work by asking whether the current argument needs it, not by counting words.

Timing, Not Brevity

A two-sentence aside can violate YAGNI. A ten-page explanation of how the results were produced can be necessary. Length does not decide.

Shakespeare made this distinction comic around the turn of the seventeenth century in Hamlet. Polonius announces that “brevity is the soul of wit,” delivers his conclusion, and then wanders into definitions, repetition, and verbal flourishes. Gertrude interrupts him: “More matter with less art.” His failure is not simply that he uses many words. The additional language consumes his listeners’ time without improving what they understand.

Shakespeare was not formulating YAGNI. He was dramatizing the problem beneath it. More language does not necessarily produce more value. Software engineering did not invent that discipline. It gave technical practitioners another vocabulary for recognizing it.

The explanation belongs when readers need it to evaluate the results. Historical context belongs when the argument depends on how an idea developed. A counterargument belongs when a reasonable reader could raise it and the conclusion must survive it. A definition belongs when the reader cannot interpret the next section without it.

An addition becomes speculative when it serves an audience, objection, application, or publication outside the present piece rather than the current argument and target audience. Common examples include:

• Background for a question the essay never asks.
• A qualification for an objection no reasonable reader is likely to raise.
• A section included because the writer completed the research.
• An abstraction created for reuse before another use exists.
• An appendix for readers who have not asked to reproduce the method.
• An explanation of how the idea applies to a field the essay does not otherwise discuss.

The distinction depends on present need. Necessary depth helps this reader understand, evaluate, decide, or act. Speculative depth prepares for a possible future conversation.

Identify the Need Before Optimizing for It

Donald Knuth’s warning makes the timing explicit:

“We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil.”

Donald Knuth, “Structured Programming with go to Statements”

Knuth’s guidance can be read as telling us to focus on the remaining 3 percent. Once the critical code has been identified, the programmer should examine it carefully. His point is not that performance never matters. Optimization should follow evidence about where performance matters.

The same timing applies to writing. Do not remove evidence, context, or qualifications merely because they make the document longer. That is not optimization. Determine what the current reader and argument require, then optimize the reading path around those requirements.

Even comprehensive technical books establish boundaries around what they will explain. The preface to Design Patterns: Elements of Reusable Object-Oriented Software states, “This book isn’t an introduction to object-oriented technology or design.” The authors assume proficiency in an object-oriented programming language and some experience with object-oriented design. The Data Warehouse Toolkit performs the same function through an expressly labeled “Intended Audience” section. Both books are thorough within their stated boundaries. Neither attempts to teach every prerequisite that a possible reader might lack.

Comprehensive does not mean complete for every possible reader. It means complete for the reader and purpose the work defines.

Chapter 5 bounded the reader-facing interface. Interface Segregation asks what this reader needs from this piece. YAGNI asks whether that need exists now or belongs to a later revision, another publication, or no publication at all.

Cheap Generation Does Not Make Speculation Free

Beck’s timing argument becomes more important when AI can generate code quickly. He argues that reducing the cost of typing does not remove the cost of speculative structure. The system still commits to assumptions before the requirement provides enough information.

AI creates the same temptation in writing. An agent can produce an industry history, an FAQ, five counterarguments, a technical appendix, and channel-specific variants in minutes. The author must still evaluate their accuracy, reconcile their terminology, decide where they belong, and maintain their dependencies. Most importantly, readers must still spend time and attention processing them.

AI also reduces the human effort required to research, organize, and preserve information. That changes what happens when an author cuts something from the current piece. The material does not have to disappear. It can remain in a source dossier, move into a future-work queue, or become the starting point for another piece. Cutting useful material from the reader’s path no longer requires discarding it.

The same capability creates another risk. An author can include more information than the current argument can use coherently. This is the authorial equivalent of overloading an agent’s context window: all the information may relate to the task, but supplying it at once makes the task harder rather than easier. AI makes cutting less destructive and promotion less expensive. It should not lower the threshold for keeping material in the current piece.

My OODA loop work began with a connection I had noticed and wanted to explore for the blog. The research exposed several related questions, and each became a piece with its own thesis.

The Loop Is the Easy Part explains orientation and agent loops. A Fighter Pilot Is Hiding in Your Engineering Practices uses the same research base to examine the idea’s origins, movement across fields, and relevance to engineering. The second piece links to the first for deeper treatment rather than rebuilding it.

The posts share a research base and perform different work. One exploration produced multiple pieces because it uncovered arguments worth developing independently. The available notes did not determine what was published.

Low generation and preservation costs can increase the amount of speculative material. The question remains whether the current piece needs any of it.

This does not mean the first draft must be architecturally perfect. Drafting is often how a writer discovers the real argument. A speculative paragraph can help the author think even when it does not belong in the publication. YAGNI becomes the editorial test: once the material has helped the author discover the argument, does the reader still need it?

Effort Does Not Create Reader Value

Before I submitted a school paper, an English teacher told me that a full page I had written served no purpose. Deleting the page hurt. She was right.

Writers become attached to material they worked hard to produce. A source took hours to find. An explanation required several drafts. An example finally says something clever. Removing any of them can feel like wasting the effort already spent.

Preserving that excess work is the sunk cost fallacy expressed as editorial judgment. The work has already been done. Keeping the material cannot recover the time, and removing it does not erase what the author learned while producing it.

Effort is not evidence that the reader needs the result.

This principle also applies to research. Collecting a source earns it consideration, not space in the essay. A useful discovery may correct the argument, support it, become a supplemental piece, remain in the research notes, or lead nowhere. The hours invested do not determine which outcome is correct.

Keep It, Cut It, or Promote It

YAGNI does not require every unnecessary passage to disappear forever. It creates three decisions:

Decision	Use it when	Result
Keep	Removing the material would break the argument, hide necessary evidence, omit a required qualification, or leave the reader without needed context.	The material remains in the current piece.
Cut	The material does not serve the current piece and does not yet support a useful piece of its own.	Remove it from the draft. Preserve a research note only when it has continuing value.
Promote	The material has a distinct question, reader benefit, evidence base, and enough depth to justify independent treatment.	Develop it separately without requiring the current essay to contain it.

Promotion is not permission to write the supplemental piece immediately. A title and a short note preserve the idea. Drafting begins when that piece has its own reader, purpose, and evidence.

These three decisions keep fear of loss from controlling the current essay. Cutting a passage does not require pretending it was worthless. Promoting an idea does not require including an undeveloped version in the current essay.

Decide What Happens to Material You Do Not Use

Not all material considered while developing this essay received the same disposition:

Material considered	Disposition	Reason
The editor as an experienced PR reviewer	Keep the core analogy	Chapter 9 needs it to explain substantive and developmental review.
Natural language as a programming language in AI systems	Reserve for a separate article	Chapter 1 needs only a bounded aside. The larger argument requires its own evidence and implications.
Paragraph contracts as unit tests	Reserve for a separate article	Chapter 4 needs only the compact parallel. A complete treatment requires more examples and stronger limits.
Complete provenance notes for every epigraph candidate	Keep in the working notes	Readers do not need the full audit in the argument.
The real-time record of researching and revising this essay	Reserve for a separate case study	The process can support an independent article without interrupting the principle chapters.

These dispositions do not guarantee that every separate article should be published. They preserve a decision: keep the material here, remove it, or develop it separately when it earns its own reader, purpose, and evidence. Until then, the material remains an option rather than an obligation.

The excluded material is YAGNI for this essay. That does not make it bad. It means it is not required here, now, for this reader.

YAGNI protects the present argument from speculative structure. It does not protect the draft from necessary revision. These principles become valuable when they stop describing a piece and start changing it. The final step is to assemble them into a repeatable refactoring practice.

9. Refactoring Prose

“Even throwing away code helps; indeed it is the sign of a good project that it does regularly throw away code.”

Martin Fowler, “Refactoring: Doing Design After the Program Runs”

A diagnostic lens has little value if it leaves the draft unchanged. Single Responsibility should cause a mixed paragraph to split. Interface Segregation should remove context intended for a different reader. Dependency Inversion should ensure that every source and example fulfills a need in the argument while the argument remains accountable to what the evidence supports. DRY should expose competing sources of truth. YAGNI should keep attractive detours out of the published piece and ensure the reader’s path to the conclusion is free of intellectual detritus.

That work is more than polishing. Nancy Sommers’s research on revision distinguishes writers who treat revision as changing words from experienced writers who reconsider meaning and structure throughout the piece. They add, delete, substitute, and reorder at several levels. Software engineers already have a familiar name for disciplined structural change: refactoring.

The term does not transfer literally. Software refactoring preserves externally observable behavior. Revision may change the argument when research, review, or clearer thinking shows that it should. The useful takeaway for an author is controlled structural revision. State what the piece must accomplish, change its components and relationships, then test whether the revision fulfills that responsibility more effectively.

Plan → Draft → Test → Review → Refactor → Publish

The workflow has six named stages:

1. Plan the intended architecture before drafting begins.
2. Draft to create the first implementation of the planned architecture.
3. Test the architecture at the document, chapter, section, paragraph, and sentence levels.
4. Review the piece with tools and people who can see failures the author cannot.
5. Refactor the structure while preserving what still works.
6. Publish when the piece fulfills its responsibility for its intended reader.

This is a cycle, not a waterfall. Linda Flower and John Hayes describe writing as a recursive process of planning, translating ideas into text, and reviewing the result. A failed test may send the writer back to research. Review may reveal that the governing question is wrong. Refactoring one section may expose a missing precondition in another. The names make the work easier to inspect without pretending that experienced writers move through it only once.

Plan the Architecture

Writing begins before drafting. An outline describes the intended architecture while its boundaries, sequence, and dependencies are still inexpensive to change.

As of August 2026, AI-assisted software development makes this separation especially visible. Anthropic recommends exploring first, then planning, then coding, and OpenAI defines Codex Plan Mode as a non-mutating mode for research and the development of a plan before implementation. I regularly use Plan Mode in the Codex app for other projects, although I did not use the formal mode for this essay. This project still began with a plan. I created a source dossier and an outline before drafting began. Planning does not depend on a product feature, but the feature gives the practice a familiar name and an explicit place in the workflow.

Governing question: What question will this piece answer?

Provisional answer: What does the author currently think the answer is?

Intended reader: What knowledge and purpose define the audience?

Reader outcome: What should the reader understand, evaluate, decide, or do?

Scope: What related questions belong elsewhere?

Section responsibilities: What distinct contribution must each planned section make?

Dependencies: What must the reader know before each section can fulfill its responsibility?

The plan is provisional. Research may challenge the answer, outlining may expose a missing dependency, and drafting may reveal that two planned sections have the same responsibility. Planning makes those decisions explicit without pretending to settle them permanently.

Draft for Discovery

Drafting is the first attempt to implement the planned architecture in a document. It turns intended responsibilities, sequence, and dependencies into something concrete enough to test. The Test stage determines whether the argument survives contact with its supporting material and whether the components work together as planned.

Drafting still needs freedom. A writer may follow a source, try an analogy, repeat an explanation, or write a section that later proves unnecessary. Discovery is allowed to be inefficient because the draft serves the author before the publication serves the reader.

Not everything produced during research and drafting belongs in the document. Source notes, discarded passages, alternate examples, and supplemental candidates can remain in separate working files. That separation lets the writer remove material from the draft without losing research or ideas that may be useful later.

Test from the Document Down

Sentence-level review is the wrong place to start, just as a code review should not begin with line-level comments before the reviewer understands the overall change. Test the largest responsibility first, then descend into the components that implement it. There is little value in perfecting a paragraph before deciding whether its section belongs.

Test	Question
Document responsibility	Does the piece answer one governing question and produce the intended reader outcome?
Chapter responsibility	Does each chapter develop one major part of the document’s governing purpose?
Section responsibility	Does each section make a distinct contribution to the argument or explanation developed by its chapter or shorter document?
Single Responsibility	Does each component have one reason to change, even when it performs several coordinated effects?
Paragraph contract and substitution	What context does the paragraph receive, what rhetorical purpose does it serve, and what may the next paragraph assume afterward? Could a replacement preserve that contract?
Open-Closed	Can evidence, examples, counterarguments, and applications change without unnecessary reconstruction of the argument?
Interface Segregation	Does this reader receive sufficient context without being forced through material intended for someone else?
Dependency Inversion	Does the argument organize its details while remaining accountable to what the evidence supports?
DRY	Where is knowledge or intent maintained independently in more than one place?
YAGNI	What belongs in this piece now, in another piece later, in the notes, or nowhere?

Tests do not make editorial judgment automatic. They make the questions explicit. A paragraph can fail because it lacks a precondition, mixes responsibilities, duplicates reasoning, serves the wrong reader, or has no present purpose. “This paragraph feels weak” becomes a diagnosis the writer can act upon.

Test again after every structural change. Moving a section can break its transition. Deleting an example can remove context a later paragraph still expects. Splitting a mixed paragraph can reveal that one half has no role at all. A refactor is complete only when the surrounding components still compose into a useful whole.

Review Is More Than a Linter

Authors know too much about their own drafts. We remember the source that made a conclusion obvious, supply missing transitions from memory, and interpret an ambiguous sentence according to what we intended. The draft works on our machine.

Review introduces another environment. Automated tools and human editors expose different kinds of failure:

These are rough parallels, not one-to-one equivalents. Editors and software reviewers have different responsibilities, and factual verification is not literally a unit test. The comparison is useful because it distinguishes mechanical checks from structural judgment.

Software development	Writing
Compiler	Grammar, punctuation, and syntax correctness
Linter or static analysis	Automated proofreading and style checks
Unit and integration tests	Factual verification and contract testing
Refactoring	Structural revision
Experienced PR reviewer	Structural or developmental editor
Focused correctness review	Copyediting and proofreading

The terminology matters. Early in the development of this project, I used copy editor to describe the experienced reviewer in this analogy. That term was imprecise.

Editors Canada and the Editorial Freelancers Association distinguish developmental or structural editing from copyediting and proofreading. Developmental and structural editors examine purpose, audience, organization, completeness, and the relationships among components. Copy editors focus more closely on correctness, consistency, usage, and style. Both forms of editing matter, but they review different risks.

Automated proofreading tools are closer to linters. They catch malformed sentences, inconsistent capitalization, repeated words, punctuation problems, and declared style violations. They can identify a defect without understanding the complete architecture.

A strong structural or developmental editor behaves more like an experienced engineer reviewing a pull request. The editor asks:

• Why does this section exist?
• What question is this paragraph answering?
• Does the conclusion depend on context the draft never established?
• Does this source support the specific statement attached to it?
• Have two components taken responsibility for the same reasoning?
• Is this example necessary, or is it merely interesting?
• Would the intended reader understand this without knowing what the author knows?

Those questions test purpose, interfaces, dependencies, evidence, and reader value. The editor is not there to replace the author’s judgment. The editor shows the author how another informed reader experiences the draft and where that reader needs information or reasoning the draft does not provide.

Refactor the Diagnosed Failure

Review should produce a reason for change, not a general request to make the writing better. A good code review identifies specific problems and suggests ways to address them. It does not simply tell the developer, “Fix this.” The diagnosis determines the operation:

Diagnosed failure	Refactoring operation
Missing reader context	Add or move the required precondition
Mixed responsibilities	Split the component
Duplicated reasoning	Establish one maintained source and revise local expressions
Evidence separated from the statement it supports	Move the evidence or reorder the argument
Paragraph with a valid purpose but weak execution	Replace the paragraph while preserving its contract
Valuable detour with an independent thesis	Extract it into the supplemental queue
Material without a present reader benefit	Delete it
Transition polished before the structure stabilized	Rewrite it after the surrounding components settle

Fowler reduces manual refactoring to two principles: “take small steps and test frequently.” The same rhythm applies to revision.

Move one section, then inspect the new handoffs. Replace one paragraph, then verify that the next paragraph still receives what it needs. Delete one detour, then search for later references that depended upon it. Changing one relationship at a time makes it easier to see whether the revision solved the diagnosed problem or created another.

Some revisions expose a larger failure. A section may resist every attempt to repair it because the thesis does not need it. Evidence may contradict the provisional answer. A new audience requirement may change the entire document interface. Refactoring is disciplined revision, not a commitment to preserve a mistaken architecture.

Return to the Opening Draft

The product-owner essay that opened this essay did not need more polish. It needed several different structural operations:

Finding	Diagnostic	Refactor
Readers were told the role was undervalued before they could recognize the problem	Interface and reader precondition	Open with questions readers could apply to their own teams
The strongest lived evidence appeared after generalized explanation	Dependency and argument sequence	Move observed results closer to the conclusion they supported
A tool pipeline occupied space that should have explained what changed for the team	Single Responsibility and YAGNI	Reduce the implementation detail and restore the section’s focus to practice and results
Hypothetical sprint math supported a point for which direct evidence existed	Evidentiary dependency	Replace the hypothetical calculation with observed refinement and release results
AI appeared before the human product-owner craft had been established	Scope and argument sequence	Establish the human practice first, then add AI as an application

The revision retained the premise that product ownership is a high-leverage practice. It changed the evidence, entry point, scope, sequence, and relationship among sections. Several sentences survived. Others moved, changed, or disappeared. The piece preserved what it was trying to accomplish while improving how its components worked together.

That is prose refactoring. The final article was not merely cleaner. It had a different architecture.

Delete Without Disowning the Work

Fowler treats regularly discarded code as evidence that a project is learning. The same interpretation helps writers separate care from attachment. A deleted section may have exposed the real argument. A rejected example may have revealed which evidence was missing. A paragraph can teach the author something and still have no responsibility in the publication. Revision asks what the intended reader needs from the work now.

Compression can require more effort than expansion. In Letter XVI, Blaise Pascal apologized for writing at length because he lacked the time to make the letter shorter. The familiar observation survives because writers recognize the labor behind it. Removing an unnecessary explanation requires the author to understand what the explanation was trying to do, preserve the necessary part, and rebuild any dependencies left behind.

Shorter is not automatically better. Deliberate is better. A ten-page explanation can survive refactoring because every part is required. A sentence can disappear because none of it is.

Give AI the Architecture to Review

AI can revise a locally fluent passage without testing whether the passage belongs. The request determines the level of review:

Paragraph-level request: Make this paragraph clearer.

Architectural request: Test whether this paragraph has a necessary responsibility, receives the context it needs, and establishes what the next paragraph depends upon.

The first request assumes the paragraph should remain. The second allows deletion, movement, splitting, or replacement. It asks the model to examine the component inside a system rather than optimize it in isolation.

PLANET studies long-form generation, not editorial review. It begins from the problem that generated passages can be fluent while the complete work remains incoherent, then tests content planning for counterarguments and opinion articles. The paper supports the distinction between local fluency and high-level coherence. Extending that distinction to the architectural review of an existing article is my interpretation.

The same class of failure appears when AI generates a large body of code in one pass. Individual files may compile and look reasonable while the system omits required behavior, violates architectural boundaries, or fails when its components interact. That software parallel is ours, not a result tested by PLANET.

XtraGPT tests a narrower revision task. Given a complete academic paper, a target paragraph, and an author instruction, the model revises the paragraph while maintaining coherence with the rest of the paper. The study supports context-aware, criteria-guided revision of scientific writing. It does not test this essay’s diagnostic framework.

My practical extension is to give an AI reviewer the architecture it must evaluate: the intended audience, governing purpose, scope, section responsibilities, and source constraints. An author-specific style guide supplies a different kind of context: standards for how the work should sound and which editorial choices should remain consistent. Neither study tests author-specific style guides. The guide is my response to preferences and editorial standards that would otherwise remain implicit.

With those inputs available, an author can ask AI to compare versions, test declared contracts, trace repeated definitions, flag likely missing context, and question whether evidence supports the surrounding statement. These are proposed review tasks, not guarantees of correct judgment. AI cannot recover an intention the author never expressed. Human judgment still decides what the piece should accomplish, which evidence is credible, which rhetorical choices are deliberate, and whether the revision sounds like the author.

Publish When the Responsibility Is Fulfilled

Refactoring can continue indefinitely. Publication requires a release decision.

In The Disciplined Codebase, I warn that refactoring can become procrastination when cleanup displaces the work the system needs now. Revising an article has the same failure mode. Once an article has fulfilled its responsibility, another round of improvement can become a way to avoid publishing.

A piece is ready when its governing question has a defensible answer, its intended reader has the context needed to follow that answer, its evidence supports the statements that depend upon it, and its components compose into the intended result. Structural review is complete when known architectural failures have been resolved or accepted deliberately. Copyediting, proofreading, link verification, and factual checks complete the correctness pass.

Ready does not mean complete for every possible reader. Chapter 8 established that boundary. It means complete and correct for the reader and purpose the work defines.

Publication creates a version, not an immutable artifact. I have republished blog posts after subsequent review and revision. Books receive new editions, and newspapers update or correct published articles. I expect this very essay to evolve.

New evidence, better examples, reader questions, or changed circumstances can justify a later revision. Publishing now does not prevent that revision. It prevents possible future improvements from postponing useful work indefinitely.

Apply the Complete Diagnostic Checklist

Use the lenses together after the document has a complete draft. Start at the document level, then descend through chapters, sections, paragraphs, and sentences only after the larger responsibility holds.

Lens	Diagnostic question
Writing architecture	Are the statements true, clear, and mechanically sound, and do the parts compose into a useful whole?
Single Responsibility	Which parts would need to change for a different audience, body of evidence, rhetorical purpose, or publication context?
Open-Closed	Can a source, example, counterargument, or application change without forcing unrelated parts of the argument to change?
Liskov Substitution	Can a replacement accept the same context, fulfill the same purpose, and establish what the surrounding argument needs?
Interface Segregation	Does the intended reader receive the required context without being forced through material for a different task?
Dependency Inversion	Does the argument define the role its support must perform while the evidence limits what the argument may conclude?
DRY	Where is the same knowledge or intent maintained independently, and which representation is authoritative?
YAGNI	What present reader need does this material serve, and what would fail if it were removed?
Refactoring cycle	Which level fails first, what operation addresses that failure, and which dependencies must be tested again?

The product-owner draft improved when it stopped being treated as a collection of sentences and became a system of responsibilities, evidence, interfaces, and dependencies. The same change in perspective applies to any technical essay, white paper, proposal, or post.

Software engineering did not invent these qualities. Good writing already depended on purpose, cohesion, context, sequence, evidence, and revision. The principles gave those relationships familiar names. The workflow turns the names into practice.

You already apply discipline to code because other people must understand, trust, use, and change it. Your writing deserves the same care.

You write great software. Write your articles just as well.

Receipts

These sources establish the software definitions, writing scholarship, professional practices, historical examples, and AI findings used in this essay. The mappings from those foundations to the diagnostic framework are my synthesis. When I extend a source through a software comparison or applied example, the relevant receipt identifies that boundary.

• Opening revision artifact. The opening comparison uses a retained early draft and the published version of “In Celebration of the Product Owner”. The table reports structural changes observed across those first-party materials.
• Code as well-written prose. Robert C. Martin’s “First Principles” uses well-written prose as a model for readable code and emphasizes meaningful names, small components, separated concerns, and an order that respects the human reader.
• English as a programming language. Andy Hunt and Dave Thomas’s The Pragmatic Programmer tips explicitly extend programming discipline to English and documentation.
• DRY as knowledge. Hunt and Thomas’s official DRY excerpt defines duplication in terms of knowledge and intent, not merely repeated text.
• Communication patterns. Jacqui Read’s Communication Patterns is the closest direct predecessor to this essay. It applies software and architecture patterns, including Single Responsibility, to sentences, paragraphs, diagrams, and other technical communication.
• Technical-writing precedent. Google’s guidance on paragraphs treats paragraphs as independent units of logic with one topic and makes the transfer of Single Responsibility into technical-writing instruction explicit.
• Writing has architecture. Rhetorical Structure Theory, developed by William Mann and Sandra Thompson, models coherent text through functional relationships among spans, including evidence, elaboration, cause, and contrast.
• SOLID definitions. Martin’s “Solid Relevance” restates the five software principles and explains how they guide cohesion, coupling, and dependency management.
• SOLID beyond classes. Part III of Martin’s Clean Architecture explains that the principles apply to coupled groupings of functions and data, not only to conventional object-oriented classes. Extending them from software into nonfiction remains this essay’s synthesis.
• The SOLID acronym. A publisher-hosted history of SOLID supports the attribution used here: Martin assembled and popularized the principles, and Michael Feathers gave the group its acronym.
• Single Responsibility. Martin’s “SOLID Relevance” defines the principle through reasons for change and also supplies the consumer-confusion test used in the Liskov discussion.
• Meaning before phrasing. George Orwell’s “Politics and the English Language” is the source for the instruction to let meaning choose the word. The extension from word choice to paragraph purpose is mine.
• Several effects, one purpose. The National Park Service’s Gettysburg Address page supplies the passage used to distinguish multiple rhetorical effects from multiple reasons to change.
• Open-Closed origin. Bertrand Meyer’s official Object-Oriented Software Construction page anchors the original distinction between a stable description and extensible capability.
• Open-Closed formulation. Martin’s “The Open Closed Principle” supplies the chapter’s software-side shorthand for extension without unnecessary modification.
• Behavioral substitution. Barbara Liskov and Jeannette Wing’s “A Behavioral Notion of Subtyping” grounds substitution in preserved properties and observable behavior rather than superficial resemblance.
• The Given-New Contract. Thomas Kent’s “Paragraph Production and the Given-New Contract” supports the treatment of paragraph cohesion as a handoff between established and new information.
• Reader context. Herbert Clark and Susan Haviland’s “Comprehension and the Given-New Contract” explains how readers integrate new information with shared context. The “works on my machine” analogy is mine.
• Consumer-defined interfaces. Martin’s “A Little Architecture” provides the software example in which each business rule defines an interface containing only the data access it needs.
• Interfaces by reader need. The Diátaxis framework organizes documentation around distinct reader needs, supporting the separation of tutorial, how-to, reference, and explanation material.
• Independent topics. The OASIS DITA specification defines modular topics that address one subject or question while remaining understandable on their own.
• Dependency direction. Martin’s “The Clean Architecture” separates high-level policy from implementation mechanisms and directs source dependencies toward the policy.
• Argument hierarchy. Barbara Minto’s Pyramid Principle supplies an established writing architecture in which a governing point determines the questions and supporting ideas developed beneath it.
• Reusable information modules. The Information Mapping methodology supports organizing technical information into bounded, reusable units with clear purposes.
• Useful repetition. The Write the Docs documentation principles provide ARID, “Accept (some) Repetition In Documentation,” as a practical limit on rigid applications of DRY.
• YAGNI as timing. Kent Beck’s “The Cost YAGNI Was Never About” explains YAGNI as a decision about when to create structure, not a demand to minimize effort or length.
• Hamlet’s date. The Royal Shakespeare Company’s dates and sources for Hamlet supports placing the play around the turn of the seventeenth century.
• Brevity in context. The Folger Shakespeare Library’s text of Hamlet, Act 2, scene 2 supplies Polonius’s statement that brevity is the soul of wit and Gertrude’s response.
• Premature optimization. Donald Knuth’s “Structured Programming with go to Statements” is the source for the chapter’s distinction between speculative optimization and an identified critical need.
• Declared prerequisites. The publisher’s page for Design Patterns: Elements of Reusable Object-Oriented Software supports the example of a comprehensive book that explicitly assumes prior object-oriented proficiency.
• Intended audience. The publisher’s table of contents for The Data Warehouse Toolkit identifies an “Intended Audience” section, supporting the example of a thorough book that still declares its boundaries.
• Revision beyond wording. Nancy Sommers’s “Revision Strategies of Student Writers and Experienced Adult Writers” distinguishes word-level changes from experienced revision that reconsiders meaning and structure through addition, deletion, substitution, and reordering.
• Recursive writing. Linda Flower and John Hayes’s “A Cognitive Process Theory of Writing” grounds the workflow in a recursive process of planning, translating ideas into text, and reviewing.
• Plan before implementation. As of August 2026, Anthropic’s Claude Code best practices recommend separating exploration and planning from implementation.
• Plan Mode in Codex. As of August 2026, OpenAI’s Plan Mode definition describes a non-mutating mode for research and the development of a plan before implementation.
• Editorial standards. Editors Canada’s Professional Editorial Standards distinguish structural, stylistic, copy, and proofreading work and relate editorial judgment to audience, medium, and purpose.
• Editorial roles. The Editorial Freelancers Association’s editorial service definitions distinguish developmental editing, line editing, copyediting, and proofreading by the kinds of problems each addresses.
• Refactoring practice. Martin Fowler’s “Refactoring: Doing Design After the Program Runs” supports behavior-preserving structural change, iterative design, small tested steps, and deletion as evidence of learning.
• The work of compression. Blaise Pascal’s Letter XVI is the source behind the familiar observation that writing a shorter letter can require more time.
• Fluency without coherence. Hu et al.’s PLANET paper tests content planning for counterargument and opinion-article generation against the problem of fluent passages without coherent high-level flow. The extension to editorial review and the comparison to one-shot AI code generation are mine.
• Context-aware AI revision. Chen et al.’s XtraGPT paper tests criteria-guided revision of a target paragraph using an author instruction and the complete academic paper as context. The extension to this essay’s diagnostic framework and an author-specific style guide is mine.