Write for the Reader, But Execute for the Machine

May 18, 2026

9 min read

4 views

84%

The Strange Mistake We Make With Instructions

Most people think the hardest part of writing instructions is being clear enough for a human. But there is a deeper problem: instructions are not always consumed in the order they are written. That sounds like a technical quirk, but it is actually a general law of communication. What appears first on the page is not always what comes first in the process. What looks like the beginning may be the conclusion. What reads like a summary may in practice be a gateway, a filter, or even a label that gets attached only after the real work is done.

That tension shows up in code comments and in database queries, but it applies everywhere. A person can read top to bottom. A system often cannot. A good writer, engineer, or thinker has to live in both worlds at once: the world of human readability and the world of operational order.

This is why some writing feels instantly trustworthy. It respects the sequence in which a machine or process actually works, while still preserving the sequence in which a person wants to understand. Great instructions do not merely explain. They bridge two different timelines.

Two Orders at Once: The Page Order and the Process Order

A SQL query looks innocent enough when you read it from top to bottom. First the data source appears, then the filters, then the grouping, then the selection of columns, then ordering, then limiting. But the engine does not carry out the query in that visual order. It begins with the data source, then applies conditions, then groups, then filters groups, then chooses the final columns, then sorts, then trims the result.

That difference matters because it reveals a basic illusion: textual order is not execution order.

The same thing happens in documentation. A docstring may begin with a one line summary, then a blank line, then a fuller explanation. It may also include additional labels for attributes or extra notes. Those conventions are not just style rules. They encode a recognition that a human reader needs a quick answer first, then depth later, while a future maintainer needs a durable structure that can be parsed, searched, and extended.

The best instructions are written like a good interface: simple on the surface, precise in the mechanism.

This is why the seemingly small rule about a one line summary matters. A short description is not an inferior version of a long explanation. It is a contract boundary. It tells the reader, in one glance, what this thing is for. Only after that does the longer explanation earn its place.

Consider a restaurant menu. The dish name is the summary line. The ingredients and notes are the fuller description. No one wants the menu to begin with a paragraph about the farm, the chef, the temperature of the oven, and only then reveal the dish. That might be honest in one sense, but it is unusable. The menu works because it is layered. The same principle governs software, legal writing, and even emails.

The real question is not whether information should be complete. It is whether it should be sequenced by comprehension or sequenced by operation. When those differ, clarity depends on acknowledging both.

Why Good Documentation and Good Queries Obey Different Truths

A docstring convention that insists on triple double quotes, a clean summary line, and a blank line before the details is doing more than prescribing style. It is teaching writers to create a structure that can survive multiple forms of use. A human glances at the summary. A tool may extract the first line. A maintainer reads the details. An editor may preserve special attribute notes. The same block of text must serve different audiences without collapsing into noise.

SQL has a similar but inverted challenge. The query is written for the reader in one order, but executed by the engine in another. That mismatch can fool beginners into making mistakes, especially when they assume the query is a story told in the same order it runs. It is not. It is more like a blueprint annotated for the contractor. The blueprint is read in one direction, but the building is assembled in another.

This gives us a useful mental model: instructional writing is often dual use.

Interpretive use: how a human makes sense of it.
Operational use: how the system processes it.

When these are aligned, the artifact feels elegant. When they are not, the artifact becomes brittle. A docstring that buries the summary inside paragraph three is hard to scan. A SQL query written in a misleading visual order is easy to misread. In both cases, the problem is not merely verbosity. The problem is a failure to honor the reader’s and the executor’s different needs.

This is why conventions matter more than many people think. Conventions are not petty rules invented by gatekeepers. They are compressed agreements about sequencing. Triple double quotes, blank lines, and concise summaries tell humans and tools where to look first. Query order tells the engine where to work first. Both are forms of choreography.

Imagine a theater production. The audience sees a curtain rise, then actors speak. But the backstage crew works from an entirely different script: lighting cues, prop placement, timing, exits. A successful production depends on both scripts being synchronized, even though they are not identical. Documentation and queries are similar. One script is for understanding. The other is for execution. Good craft keeps them compatible.

The Deeper Lesson: Structure Is a Moral Choice

It is tempting to treat formatting as a cosmetic concern. But structure shapes behavior. The order in which you present information determines what people notice, what they assume, and what they remember. That is not merely aesthetic. It is ethical.

If you lead with a long explanation before stating the summary, you force readers to work before they know why they are working. If you organize a query in a way that mimics human storytelling but obscures the engine’s logic, you increase the chance of error. If you leave conventions vague, you make future readers pay a tax on every revisit.

In this sense, concise summaries are acts of respect. They acknowledge that the reader deserves a fast orientation. Full descriptions are also acts of respect. They acknowledge that nuance matters once orientation is established. The blank line between them is not empty space. It is a signal that says: first understand what this is, then learn how it behaves.

This sequence is powerful because it mirrors the way people actually think under uncertainty. We do not start with detail. We start with a name. Then we ask whether the thing is relevant. Then we dive deeper if it is. The one line docstring formalizes that cognitive path. A query, meanwhile, formalizes a different path, one in which the machine must first gather rows, then filter them, then group them, then display the result. The writer’s job is to make both paths legible without confusing one for the other.

Here is a practical analogy: think of a museum exhibit. The title plaque tells you what you are looking at. The wall text gives context. The curator may have arranged the room in a specific historical or thematic order, but the visitor does not experience the exhibit by assembling each artifact from scratch. The exhibit succeeds when the signage, layout, and sequence all cooperate.

That is the hidden commonality between documentation style and query execution. Both are attempts to manage sequence under constraint. One optimizes for people reading. The other optimizes for systems computing. In both cases, the craft lies in making the order feel natural without pretending there is only one order.

Clarity is not the absence of complexity. It is the right complexity in the right place.

A Better Mental Model: Write in Layers, Think in Phases

The most useful way to connect these ideas is to stop thinking of communication as a single line and start thinking of it as layers plus phases.

Layers are for readers. They answer: what is this, why does it matter, what are the details?
Phases are for execution. They answer: what happens first, what depends on what, what is evaluated when?

A strong docstring uses layers. It begins with the smallest possible truthful summary, then expands. A strong query is often written with the engine’s phases in mind, even if the text appears top to bottom. A strong explanation, policy, or spec should do both: tell the reader enough to orient themselves quickly, while preserving the true dependencies underneath.

This model helps explain why many documents fail. They either become all layer and no phase, meaning pleasant but operationally vague, or all phase and no layer, meaning precise but hard to enter. The sweet spot is a two step structure:

Orient: give a short, obvious summary of the thing.
Unfold: reveal the dependencies, exceptions, and mechanics in the order that matters for use.

Think about writing a recipe. The title tells you the dish. The intro tells you why you might want it. The ingredient list gives you the inventory. The steps tell you the sequence. If the recipe mixed all of those into one flowing paragraph, it would be harder to cook from, even if every word were accurate. Good recipes are not just descriptive. They are executable.

That is the kind of writing both traditions point toward. A good docstring is executable by the reader’s attention. A good query is executable by the database engine. A good piece of prose aims for both: it must be understood before it can be useful, but it must also be useful in the order in which it will be used.

This is why the best technical communicators develop a kind of double vision. They ask, at every sentence: how will a human scan this, and how will a process consume it? Not because every text is code, but because every serious artifact has a life beyond the moment of writing.

Key Takeaways

Do not confuse visual order with operational order. What appears first on the page may not be what happens first in practice.
Lead with orientation. A short, truthful summary helps readers decide how deeply they need to engage.
Use layers for humans and phases for systems. Clarity improves when you separate comprehension from execution.
Treat conventions as structure, not decoration. Rules about formatting often encode how information should be consumed.
Write for future use, not just immediate reading. The best text remains understandable when revisited by a person, tool, or process months later.

The Real Lesson Hidden in Plain Sight

The deepest connection between a docstring and a SQL query is not that both are technical. It is that both expose a universal problem: how do you write something that is read one way but must work another way?

That problem appears in software, but also in management memos, legal contracts, lesson plans, and even the way we explain ourselves to other people. We often want to tell the story in the order that feels natural to us. But the listener, reader, or system may need the pieces in a different order to make sense of them or act on them correctly.

So the next time you write a comment, a query, or any structured explanation, ask a more interesting question than “Is this clear?” Ask: clear to whom, and at what stage?

That question changes everything. It moves you from writing as if language were a single straight line to writing as if it were a bridge between two timelines. The first timeline is understanding. The second is execution. Master both, and your words will do more than describe the world. They will help it run.