Avoiding murk
The one-letter complaint
Jonathan types t. Translate. It means the sentence just written could not be read, and he wants it again in words that work.
Murk is writing that is challenging to understand. That is the whole definition, and it is enough, because the person who cannot read a sentence is never the person who wrote it. The writer sees through his own words to the thing behind them. Every clause looks load-bearing from the inside.
Which is the first hard fact about murk: you cannot find it by rereading your own draft. You find it by watching a reader fail. t is that failure, arriving as one keystroke.
Nine strategies
- Add up what your rules spend before you cap what they may spend. A rule set with a length limit and three rules that cost length is not a style guide, it is a squeeze. What comes out of a squeeze is compression — clauses stacked, connectives dropped — and compression reads as murk.
- Every ban needs a replacement standing next to it. A lexicon, one settled word per thing, is worth more than any number of prohibitions, because it is the only kind of rule that makes a sentence shorter as well as plainer. Ban a name without supplying its replacement and you have not removed jargon, you have made the writer improvise a private one, differently, every time.
- A swap that changes the meaning is a fault in the rule, never in the sentence. Turn the table around: state the word to reach for, and let the banned one be the footnote.
- What is measured is what gets obeyed. Leave clarity unmeasured beside a mechanically enforced word list, and the writer will spend his attention on the word list — correctly, because that is the only part with consequences.
- A guide teaches twice, once by what it says and once by how it reads. The second lesson is the stronger one, and it is the one nobody proofreads.
- Enumerate every part of the machine before repairing any one of them. In the case behind this guide, two parts collected twelve causes and three parts were never examined at all — a fair description of most post-mortems.
- Know which of your constraints belong to the carrier. Some are unfixable from inside. Naming one as unfixable is the repair — it stops the argument from restarting every month.
- Before building an instrument, look for the complaint you are already receiving. The reader has been signalling failure all along, for free, and in a form specific enough to log.
- Publish the count even when it cannot attribute. A number that cannot say which change did it is still the only thing that can say whether to keep going, and a floor you can see beats a ceiling you cannot.
In one line: murk is invisible to its author, so it can only be found by counting the reader's complaints — and the rules written to prevent it are, more often than anyone expects, where it comes from.
Where each one came from
Every strategy above was pulled out of one case: this collection's own rule set, which was found to be manufacturing the murk it forbade. The hypothesis, the twelve causes, the counting hook and the daily rate all live in the record — murk.md.
That record is still open. Six of the twelve causes are closed, and three parts of the machine have never been examined.
What it touches
- voice.md — how prose in files should read.
- lexicon.md — the replacement half of strategy 2.
- banned words.md — the ban half, kept where it does no harm.
- hooks.md — what fires before a message and after a reply, including the counter.