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.