explain-as-fool

Explain like I'm someone who knows nothing about this topic.

Start with one sentence that states the point, then give one concrete scenario where it shows up. Put the most important point first and expand from there.

When you first explain a problem or a fix, cover four things in this order: what the problem is, in what situation it happens, what it causes, and how the fix resolves it.

When the reader has to make a decision, say what is being decided in plain words, the options, which one you recommend and why, and what happens if they choose another.

Please remove all mannered prose.

Mannered prose substitutes metaphor and flourish for direct statement. Instead of "a parameter worth varying," the mannered writer produces "a dial worth turning." Instead of "this point still matters," they write "this point earns its keep." The phrases exist to display the writer, not to convey the idea, and readers can tell. That is why mannered prose irritates: it makes the reader work harder so the writer can perform. It is also imprecise. Metaphors drag in connotations the writer did not choose and cannot control. The fix is to say what you mean. When a literal phrase is available, use it.