Technical Prose

Technical prose

This skill owns what carries a fact to its reader — at the scale of a word, and at the scale of the material around it, including how many claims one sentence carries. It does not own whether a unit is a fragment or a sentence.

That boundary is not a division of labor; it follows from what varies between readers. A word carries the same fact wherever it lands — "gracefully handles" is a promise with no content in a doc comment, a README, and an error message alike, so one rule serves all three. So does a clause chain: three claims joined by "and" cost the same reading in a doc comment and a README. Grammar does not travel: a doc comment sits beneath a declaration that already supplies its subject and its article, while a README paragraph stands alone and must supply both. A rule that mandated complete grammar everywhere would be right for one and wrong for the other.

So the calling skill decides articles and whether fragments are correct at its sites. This skill never overrides those, and a rewrite that converts a fragment to a sentence — or the reverse — is out of scope here.

The same test admits a paragraph: one restating the paragraph above it carries no fact anywhere, exactly as the empty word does not. So the ladder below is in scope and fragment-versus-sentence is not — one asks whether material earns its place, the other what shape the survivors take.

The reader is not you

Naming the reader comes first. Nothing below is applied until you can say who will read this and what they lack that you hold now — the diff, the thread, the meeting, the last hour. The reader is inherited when the user or a calling skill names one, and inferred when the artifact does: a doc comment is read by the file's next editor, a commit body by whoever has the log and the diff open. When neither settles it, ask. A reader chosen on a guess is the default failure with the guess in your place: writing for yourself a minute ago. A writer cannot un-know what they know, so the gap never shows from the inside.

The cold read. Reread as the named reader. Every phrase that resolves only because you were in the room gets its referent stated: "this arc" becomes the review it names; "operator-chosen label" becomes what the label is and where it lives. Grammar does not catch these: "this arc" is well formed and carries nothing.

Content before style. Run the cold read before the word pass. Tightening cannot find a missing noun: in the session that produced this rule, two rewrites of one commit body each carried an unresolved referent through untouched, and each was caught by a reader asking "what's that?"

What ships with the text sets the bar. A commit body ships with its diff. A backlog entry, a journal line, or a message found by grep ships alone.

A metaphor standing where the fact should be is the same failure at the word scale. "A wrong answer wearing a right one's clothes" costs every future reader a decoding to recover "output that looks correct and is not".

Modality

Modality is the load-bearing part of a technical sentence, because it is what separates a requirement from an observation. It is also where hedging does its damage: a requirement written as a suggestion is not a softer requirement, it is a different claim, and a reader who acts on the difference is acting correctly.

The one exception: may not is a prohibition, and it survives intact. The ladder above maps possibility onto can, which is correct for "this may fail" but destroys "callers may not hold the lock across an await". Rewriting that to cannot claims the compiler prevents it, and to can inverts the rule. When may marks permission rather than possibility, leave it alone.

Prohibitions and obligations keep must, may not, or never in every form, including shortened ones. Dropping the modal to save a line converts a rule into a description of the present, which licenses the very edit the sentence existed to prevent.

Words that carry no fact

The test is not formality; it is whether deleting the word changes what the reader knows. If it does not, delete it rather than replacing it.

Two of these deserve their reason stated, because they look like content and are not. "Gracefully handles" names a quality of the handling instead of the handling, so a reader who needs to know what happens still does not; it is the single most common way agent-written prose describes behavior without stating it. "Robust" and its neighbors assert a property the reader cannot check — if the property is real it has a measurement, and the measurement is the fact.

One item, one name

Pick one term per thing and keep it for the whole document, and across a document and the sites that point at it. Synonym rotation reads as variety to the writer and as three distinct things to the reader, who has no way to know that "the executor", "the runner", and "the scheduler" are one object.

This matters most at a boundary: when an explanation lives in one place and other sites refer back to it, a renamed reference breaks the association it existed to create.

Rotation is worth catching in both directions. One name for two things is the worse failure of the two, and it hides better.

One spelling: American

Write color, not colour; behavior, not behaviour; -ize, not -ise; gray, not grey; judgment and acknowledgment without the middle e.

This is the same rule as one item, one name, applied to the word rather than the thing. Mixed spelling inside one document reads as several authors who did not talk to each other, and it costs the reader a half-second of wondering whether the difference is meaningful. It never is.

Two carve-outs, both absolute:

• The user's choice wins. If the user or the project asks for British spelling, or for any other convention, use it and keep it consistent. This rule sets the default, not the policy.
• Untouchables stay untouchable. A colour inside an identifier, a flag, a configuration key, a quoted error, or a cited third-party title is a name. Renaming it breaks the artifact, exactly as the section below says.

The rest

• Actions are verbs, not nouns. "Compress the file", not "perform compression of the file". A nominalized action needs a verb to carry it, and the verb it gets is always empty — perform, conduct, undertake.
• Active voice, except where the actor is genuinely unknown or irrelevant. Passive hides who acts, which is exactly the fact an instruction needs.
• One claim per sentence. A sentence chaining clauses with "and", "but", "so", or a dash hands the reader several claims to hold at once. Split it. Whether the pieces are sentences or fragments is the calling skill's call; that each carries one claim is this one's.
• Parallel ideas in parallel form. Items that do the same job get the same shape: "both need a label with whitespace, and both match the pattern" keeps its "both"; a list whose first item is a sentence and second a fragment has changed shape without changing meaning, and the reader looks for the meaning.
• No phrasal verbs where a single verb exists: "set up" is configure or install, "go down" is decrease or stop, "spin up" is start.
• No Latin abbreviations. "e.g." is "for example", "i.e." is "that is", and "etc." is a refusal to finish the list — name the items or write "and more".
• State the condition before the command. "If the network is slow, increase the timeout" beats the reverse: the reader who does not meet the condition stops reading one clause earlier, and never loads an instruction that does not apply to them.

The cheapest form that carries the fact

Borrowed from ponytail, whose ladder has an agent stop at the first rung that solves the problem rather than writing the fullest thing it can. Walk it before writing, and again when cutting. Stop at the first rung that carries the fact intact.

1. Nothing. The named reader already holds it, or a sentence nearby already says it. Not the writer: this is the rung the curse of knowledge picks.
2. A word added to a sentence that already exists.
3. A clause.
4. A sentence.
5. A paragraph.
6. A section with a heading.

The drift is upward and invisible one step at a time: a clause becomes a sentence, then a paragraph with a lead-in, then a section, and no single step looks wrong.

Be lazy about the prose, never about the thinking. A rung is chosen after the material is understood, not instead of understanding it. A short paragraph written to avoid working out what is true is worse than the long one it replaced.

Cut assertions before examples. When a paragraph and the example under it say the same thing, the example survives. It shows; the paragraph asserts, and an assertion is what the reader was going to take on trust anyway.

Never cut: modality, the subject of a claim, negations, scope qualifiers, quoted evidence, and everything under Untouchables. A rung that loses one of these is not available, and the shortening that drops one is not a shorter text — it is a different claim.

A document that states a bar is subject to it. An instruction file arguing for succinctness in three hundred words has refuted itself, and its author is the reader least likely to notice.

Untouchables

Never rewrite these, even when they break every rule above:

• Code, inline code, identifiers, CLI commands, flags, and file paths. The run in sqlpipe run --config is a name, not a verb.
• Quoted error messages and log lines. They are matched against reality.
• Product names, API endpoints, and configuration keys.
• Anything inside a code fence.

A de-slop pass that edits an identifier has broken the artifact it was cleaning. When a rule and a name conflict, the name wins silently.

Rationalizations

Red flags

• A reader chosen without the user, a calling skill, or the artifact naming one.
• A demonstrative with no antecedent in the text: "this arc", "that fix", "the review".
• A noun phrase that resolves only for someone who was in the room.
• A tightening pass that finished without a cold read.
• A metaphor or coined compound standing where the fact should be.
• A sentence joining three or more clauses with "and", "but", "so", or a dash.
• A requirement whose only modal is should.
• A paragraph that would be equally true with its first sentence deleted.
• A metaphor restating the rule its own paragraph just stated.
• An opening that establishes an audience the rule already implies.
• A document that states a bar its own prose does not meet.
• may rewritten to can without checking whether it marked permission.
• An adjective asserting a quality with no measurement anywhere near it.
• A sentence that survives deletion of its first six words with no loss.
• The same object under two names in one document, or under a different name at a site that points back to its explanation.
• "Perform", "conduct", or "undertake" followed by a noun that is really a verb.
• A rewrite whose diff touches an identifier, a flag, or a quoted error string.
• A condition trailing its command in an instruction.
• Two spellings of one word in a document, or a spelling changed inside an identifier or a quoted string.

Attribution

The vocabulary substitutions are adapted under the MIT license from AminBlg/SimpleEnglish, whose slop table is that project's original work rather than ASD material. The remaining rules paraphrase ASD-STE100 Simplified Technical English, restricted here to its reader-agnostic vocabulary rules.

Five rules restate Strunk and White, The Elements of Style: omit needless words, use the active voice, use definite and concrete language, keep parallel ideas in parallel form, and avoid a succession of loose sentences.

The reader rule follows Steven Pinker, The Sense of Style, on the curse of knowledge as the primary cause of unclear expert writing, and Google's technical writing guidance on knowing the audience.

This skill is unaffiliated with ASD and STEMG and is not an STE compliance tool. ASD-STE100 is a registered trademark of ASD; the official standard is a free download at asd-ste100.org.