Fable writing

Fable Writing

Core thesis: the reader pays for everything. Every sentence costs attention; the writer's job is to spend it on the reader's behalf. Good writing is not compressed — it is selected: few things, fully said, in the order the reader needs them.

Before writing

• Name the reader and their question. One sentence: who reads this and what do they need to know or do afterwards. Every inclusion decision traces back to it.
• Write the lead first: the single sentence the reader would keep if they kept only one. It goes first in the document — not after the warm-up.
• Choose what to omit. The strongest edit happens before drafting: facts that do not change the reader's action or understanding do not enter.

The rules

1. Lead with the outcome. First sentence answers the question; background follows for those who read on. Never make the reader excavate the point.
2. Write for the reader who was not there. No private shorthand, no labels defined three paragraphs ago and referenced by number, no codenames from your process. Terms spelled out in place.
3. Complete sentences; compression by selection. Cutting content beats mutilating prose. No fragment chains, no A → B → fails arrows in prose, no telegraphese.
4. Order by the reader's priority, not your chronology. "First I looked at X, then I tried Y" is a diary, not a report. Findings first, method after, process only if it changes trust in the findings.
5. Concrete beats abstract. Numbers, names, examples. "Slow" is a mood; "900ms on a 3-item list" is a fact. One example does the work of three adjectives.
6. Calibrate every claim. State what is verified as verified, what is assumed as assumed, and what would resolve the assumption. Hedge only where uncertainty is real — then hedge once, precisely, not with a fog of "might/perhaps/possibly".
7. Structure by need, not by habit. Prose carries reasoning; lists carry genuinely enumerable items; tables carry comparisons across two axes. Headers appear when a document is long enough to navigate, not to decorate a paragraph.
8. One idea per paragraph, and the first sentence of the paragraph is that idea.
9. Cut ritual. Openers that restate the question, "It's important to note", "In conclusion", "As mentioned above", summary sections that summarize the summary. If a sentence would survive in any document, it belongs in none.
10. Read it back as the reader. Fresh pass, top to bottom: every place you stumble, the reader falls.

Form-specific contracts

• Documentation: document the contract and the why, not the visible how. Examples before reference; quickstart before completeness. Every code sample runs as pasted. The doc is wrong the moment it drifts — write the minimum that stays true.
• README: what it is (one line), why it exists, quickstart, then depth. A reader decides in 30 seconds whether this is for them — design for that reader.
• PR descriptions: what changed and why in the first two lines; how it was verified; what reviewers should look hardest at. Reviewers are the reader.
• Commit messages: subject = the change as an imperative fact ("Fix legacy accounts bypassing usage mapper"); body = why, and what would break without it.
• Error messages & UX copy: what happened + what to do next, in the user's vocabulary. Buttons are verbs. No blame, no cuteness in failure paths, no "Oops".
• Announcements/emails: the ask or the news in sentence one; details below; one call to action, not three.

The rubric

Score 0–2 each before delivering (feeds the fable-core Gauntlet). Any 0 blocks delivery.

1. Lead — the first sentence is the takeaway. Test: delete everything but sentence one; does the reader still get the point?
2. Reader fit — assumed knowledge equals the reader's actual knowledge. Test: name the reader; find one term they wouldn't know — is it defined in place?
3. Selection — nothing present that changes neither action nor understanding. Test: for each paragraph, name what the reader loses if it's cut. No loss → cut.
4. Clarity — one-pass parseable, complete sentences. Test: read aloud; every stumble is a defect.
5. Concreteness — claims carry numbers, names, or examples. Test: find the vaguest sentence; can it be made specific or should it be deleted?
6. Calibration — verified/assumed/unknown are distinguishable. Test: could a reader act on a hedge as if it were a fact, or on a fact as if it were a hedge?
7. Order — priority order, transitions carry logic. Test: would the reader ever ask "why am I being told this now?"
8. Economy — no ritual phrases, no symmetry padding. Test: count sentences that would survive in any document on any topic.

The anti-pattern catalog

Check by name in the Gauntlet:

1. Throat-clearing — a paragraph of context before the point → point first.
2. Chronology dump — the report retells your process in order → findings first.
3. Buried lede — the key fact in paragraph four → promote it to sentence one.
4. Fragment compression — arrows, telegraphese, jargon chains → complete sentences; cut content instead.
5. Hedge fog — might/perhaps/possibly carpeting every claim → hedge once, precisely, with what would resolve it.
6. Inflation — comprehensive, robust, seamless, production-ready → demonstrated or deleted.
7. Private shorthand — process codenames, "Option B", "the second issue" → say the thing in place.
8. List abuse — bullets carrying an argument → prose for reasoning; bullets for items.
9. Symmetry padding — sections stretched so headings match in weight → sections are as long as their content.
10. Empty summary — "In summary, we discussed..." → the summary states conclusions, or it dies.

Exemplars

Read references/exemplars-writing.md to calibrate — a report, a README, failure copy, and a PR description, each shown mid and fable side by side.