Persuasive Technical Writing

Persuasive Technical Writing

Turn raw technical findings into human-sounding, high-retention long-form prose. The rules below are ordered by impact against six failure symptoms; each priority names the symptom it fixes, so jump to your problem. Every rule is mechanically checkable: where a rule states a number, that number is the test a reviewer or a later pass runs with a grep or a count.

How to use

Run two passes, never one. Pass 1 builds structure and argument: Priority 2 (cohesion), Priority 3 (section titles), Priority 5 (analogies). Pass 2 is a mechanical prose linter over the countable rules: Priority 1 (cadence and blacklist), Priority 4 (quotes), Priority 6 (bolding and hook). Do not lint before the argument holds, and do not ship before the lint passes.

Priority 1: Human cadence and anti-AI rhythm (fixes "does not sound human")

• Rule 1.1 (Gary Provost burstiness rule): Never write three consecutive sentences of similar length (within ±3 words). In every 200-word block, enforce at least one short punch sentence (<7 words) and at least one rhythmic compound sentence (>25 words).
• Rule 1.2 (hard lexical blacklist): Strictly ban the Kobak et al. excess words. Zero instances permitted. Grep the draft for each token:

  delve, tapestry, testament, beacon, pivotal, intricate, realm, underscores,
  harnessing, multifaceted, interplay, moreover, furthermore, in conclusion, at its core

• Rule 1.3 (de-symmetrization): Ban symmetrical parallelism (not only X, but also Y; from X to Y and beyond). Break formulaic 3-part bullet lists into continuous narrative paragraphs.
• Rule 1.4 (Williams character-action rule): Express characters as grammatical subjects and core actions as active verbs. Ban empty openings (There is, There are, It is important that) and strip nominalizations ending in -tion, -ment, -ance.

Priority 2: Cohesion and information pacing (fixes "hard to stay with")

• Rule 2.1 (Williams given-before-new): The first 6-8 words of every sentence must connect semantically to a concept established in the immediate prior sentence. Place novel, complex, or heavy technical terms strictly at the end of the sentence (the stress position).
• Rule 2.2 (mobile paragraph ceiling): On mobile and X viewports, cap paragraphs at 1-3 sentences (maximum 40-60 words). Never stack two 3-sentence paragraphs; alternate with 1-sentence pivot paragraphs.
• Rule 2.3 (Minto problem-first flow): Introduce technical solutions only after establishing the Situation and Complication. Maintain forward causal momentum; every paragraph must answer the question raised by the preceding one.

Priority 3: Argumentative section titling (fixes "section titles unclear")

• Rule 3.1 (headline-as-conclusion): Every H2 and H3 header must be a complete, active assertion stating the causal finding of that section. Strictly forbid descriptive noun labels (Background, Architecture, Considerations, Analysis).
• Rule 3.2 (the standalone skim test): A reader reading only the H1 and H2s in sequence must be able to understand the complete logical deduction of the essay without reading the body text.

Priority 4: Quotation integration (fixes "quotes do not flow")

• Rule 4.1 (the 3-part quotation sandwich): Never drop an orphan quote. Every quotation must follow:
  1. Lead-in claim: state what the quoted speaker demonstrates.
  2. Direct quote: ruthlessly trimmed to the decisive 10-25 words.
  3. Operational translation: state what this quote means for our thesis.
• Rule 4.2 (quotation length ceiling): Inline quotations must not exceed 25 words. If an excerpt exceeds 25 words, either trim it with ellipses or pull it out into a distinct visual asset or screenshot.

Priority 5: Analogy construction and boundary protocol (fixes "no analogies")

• Rule 5.1 (mandatory physical base): Every complex abstraction (cryptographic primitive, concurrency model, distributed consensus) must map to a concrete physical system.
• Rule 5.2 (Glynn's boundary declaration): Every analogy must explicitly state where it breaks down using the exact syntactic formula:

  This functions like [Base] because [Relational Mapping]. However, the analogy breaks down at [Boundary Condition] because [Target Divergence].

• Rule 5.3 (domain lock): Lock one analogical domain per section. Never mix metaphors (for example, do not combine hydraulic plumbing with aviation engines).