write

name	write
description	Write, rewrite, and edit text for clarity, concision, and precision using Eva Parish's editing principles. Use whenever drafting or editing prose, docs, comments, PR descriptions, plans, specs, messages, or user-facing text.

Write

Apply these writing and editing principles (from Eva Parish's "How I Edit") whenever drafting or rewriting text. The goal is always: say exactly what you mean and remove all unnecessary words.

Process

1. Identify the purpose - Before editing, determine the main point and intended audience. If the text can't be summarized in one or two sentences, it lacks coherence.
2. Apply the principles below in order of impact.
3. Preserve the author's intent - Editing refines expression, not meaning.

Principles

Decide what you're actually saying

Ensure the text says what it means to say. Every paragraph should serve the main point. Cut or rewrite anything that doesn't.

Repeat yourself (within reason)

• Restate the main point at the beginning and end.
• Replace demonstrative pronouns ("this", "that") with explicit nouns.
  • Before: "We only have two boxes left. To solve this, we should order more."
  • After: "We only have two boxes left. To solve this shortage, we should order more."

Simplify

Remove words. Eliminate fluff. Get to the point.

• Cut "You should"/"You can" - Use the imperative.
  • Before: "You should save the file to your home directory."
  • After: "Save the file to your home directory."
• Cut "You will need to" - Same idea.
  • Before: "You will need to run this script."
  • After: "Run this script."
• Rewrite "of"/"for" clauses - Put information before the noun.
  • Before: "The manager of the team responsible for marketing"
  • After: "The marketing team's manager"
• Split long sentences into multiple shorter ones.
• Add commas after subordinate clauses at the start of a sentence.
  • Before: "If you're looking for me I'll be in my office."
  • After: "If you're looking for me, I'll be in my office."

Eliminate passive voice

Passive voice obscures who performs the action. Rewrite to active.

• Before: "The fire alarm was pulled and the building was evacuated."
• After: "The fire marshal pulled the alarm and the employees evacuated the building."

In technical writing, if you can't name the actor, you may not understand the system well enough.

Don't use adverbs

Replace adverbs with more specific verbs or descriptions.

• Before: "He laughed loudly."
• After: "He laughed with the kind of booming abandon that made the whole restaurant turn around."

Strip hedging adverbs ("basically", "essentially") entirely. Commit to what you're saying.

Don't assume knowledge

• Spell out acronyms on first use: "time to first byte (TTFB)".
• Add a brief explanation when introducing a concept.
• Link to further reading where appropriate.

Be aware of your tone

Be consistent. Don't mix colloquial and formal registers in the same piece.

• Before: "We were really into this new framework for like a minute, but the metrics captured by the system do not correspond precisely enough to our investigative goals."
• After: "We were initially enthusiastic about the X framework, but it did not capture the metrics we needed."

Avoid jargon and cliches

Say exactly what you mean instead of relying on idioms, business jargon, or slang.

• Before: "tl;dr, if you can hack something together by EOD, that would be great."
• After: "Can you deliver a prototype by the end of today?"

Make use of whitespace

• Break long paragraphs into shorter ones.
• Use subheadings for structure.
• Use lists instead of dense paragraphs.
• Use tables for reference information.
• Use bold for key points that skimmers should catch.

Output format

When writing or rewriting, produce the revised text directly. If the changes are substantial, add a brief summary of what changed and why after the rewritten text.