Technical Writing as Reasoning

You do not fully understand something until you can write it down so that a stranger could act on it. Vague writing usually hides vague thinking, and the page is a cheap place to find out. This page gives a five-step method for turning a technical judgment into a recommendation that can be checked.

The method is a practical synthesis, not a single authority's doctrine. Its parts rest on long traditions in logic and clear prose. Provisional

Why writing is the test

Explaining silently to yourself feels easy because gaps are filled in by the mind. On the page they stay empty. When a sentence will not come, the problem is usually that you do not yet know which of your beliefs are observed, which are inferred and which are assumed.

Orwell's 1946 essay argued that sloppy language and sloppy thought feed each other. The claim is partly an observation about habits and not a proven law, but it matches a common experience: rewriting a paragraph often changes the conclusion. This is the liberal-arts payoff applied to engineering. Writing is the grammar and rhetoric of the trivium, used on real systems.

The five steps

1. Define the problem and any ambiguous term. "Slow", "down" and "secure" each hide a measurement. Say which one you mean. This is the move Socrates repeatedly demands of his interlocutors; see the elenchus and Observe, Define, Represent: The First Three Moves.
2. Separate observations, inferences and assumptions. An observation is what a tool or a person actually saw. An inference is what you concluded from it. An assumption is what you needed to believe to conclude it. Label them, even in your own notes.
3. State the strongest competing explanation or design. If you cannot say what the best opponent would argue, you have not tested your view. See Hypotheses, Predictions and Tests.
4. Say what evidence would change your conclusion. A conclusion that nothing could overturn is a belief, not a finding.
5. Rewrite the recommendation so someone else can act on it. Lead with the recommendation, then the reasons, then the limits. The pyramid principle in Minto's book recommends this ordering for readers who are short of time.

A worked contrast

Before: "The reports are unreliable, we should switch tools."

After: "Problem: on three of the last ten days the nightly report showed all services healthy while one data source had not responded. Evidence: the source's last-update time was over a day old on each of those days. Uncertainty: I have not checked whether the delay is in the source or in our collection. Recommendation: add a freshness field and show any stale source as unknown. Verification: feed the report a deliberately stale sample and confirm the overall status is not green."

The second version commits to something that can be proven wrong. (The example is invented for illustration.)

The weekly five-sentence rewrite

Once a week, rewrite your current project in exactly five sentences: problem, evidence, uncertainty, recommendation, verification. Ten minutes is enough. Over a few weeks you will see which sentence you most often cannot write. That is your actual gap, and it is a more reliable guide than a feeling of fluency.

Countering the articulate-but-unchecked answer

A fluent explanation is persuasive whether or not it is right. This applies to confident colleagues and to AI systems alike; language models produce well-formed prose regardless of whether the claim underneath is true. The defense is the same for both: apply steps 2 and 4. Ask which parts are observed, which are assumed, and what would show the answer wrong. The habits in Working with AI Coding Agents: A Disciplined Loop rest on this, and so does the diagnostic practice in Evidence-Based Troubleshooting: Separating Explanations.

Decision records

When a choice will outlive the conversation, write it down. Michael Nygard's 2011 essay proposed short "architecture decision records": context, decision, status and consequences. A useful comparison of options covers four things:

Then add the sentence most records omit: name the requirement that would reverse the choice. If the budget halves, or the team grows, or the data doubles, which option wins instead? Stating this turns a verdict into a conditional, which is more honest and easier to revisit.

The handoff test

Give your write-up to someone who was not in the room and ask them to carry it out, or to explain it back. Do not narrate. Wherever they stumble, the text has a hole. The same idea underlies blameless postmortems in the Site Reliability Engineering book (chapter 15): a record is good if it lets others learn without needing the author.

Where the proof structure comes in

A recommendation has the shape of an argument: premises, an inference, a conclusion. Checking whether the premises are true and the inference valid is the subject of Proof and Precise Reasoning: From Arguments to Theorems. You do not need formal notation, but you do need to know that a true conclusion can follow from a bad argument and that this gives you no reason to trust it. For the larger career picture, see Building a Career on Capabilities, Not Tools, and for a sustained exercise, Twelve-Week Arcs and the Capstone Project Method. For the writing craft itself, see English Expression Mastery: Words, Sentences, Paragraphs and Speech.

Try this

1. Take a technical problem you recently solved. Write the five-sentence version and underline each assumption. Pick one and say how you could test it.
2. Choose two ways of doing the same small job (for example, storing records in a file or in a small database). Write a one-page comparison across requirements, dependencies, burden and recovery, ending with the requirement that would reverse your choice.
3. Hand a write-up to a friend and ask them to restate your recommendation without looking at it. Revise until they can.

Further reading

• Orwell, "Politics and the English Language" (1946): short and still bracing.
• Williams and Bizup, Style: Lessons in Clarity and Grace: how to make sentences say who does what.
• Minto, The Pyramid Principle: ordering a recommendation for a busy reader.
• Nygard, "Documenting Architecture Decisions" (2011).
• Beyer et al., Site Reliability Engineering (2016), chapter 15, on postmortems.