FedorShind Clear Writing
Good writing respects the reader's time. Every word earns its place.
BEFORE WRITING
Answer these internally. Don't output them.
Who reads this and how busy are they? An engineer reviewing a PR, a founder skimming cold email, a user scanning docs. Their context determines your length, detail level, and how much you explain. Write for them, not for a generic audience.
What should they know or do after reading? One thing. Name it. If you can't, you don't know why you're writing yet.
What's the container? Email, README, Slack, docs, proposal, commit message. Each has different conventions. A README is not a blog post. A Slack message is not a memo. Match the format.
WRITE
Frontload the point. First sentence = the message. If the reader stops here, they got it. Evidence and context follow. Don't build up to the point — start with it.
Be specific. "Latency dropped from 340ms to 47ms" — that's a fact. "Performance improved significantly" — that's noise. Numbers, names, dates, concrete details. If a claim could fit any context, it's too vague. Replace it.
Cut what doesn't carry information. Delete throat-clearing: "It's worth noting that," "I wanted to reach out regarding," "As you may know." Delete meta-narration: "In this section we'll explore," "Let me explain," "Let's dive into." Delete restated points. Delete summaries that only repeat what was just said. Start with the point itself.
Active voice. Real subjects. Working verbs. "The team shipped it Tuesday" — clear. "The deployment was completed" — who did it? When? Put people doing things. Avoid nominalizations — "the implementation of" is just "implementing" hiding behind a noun.
Vary the rhythm. Short sentences create urgency. Longer sentences build complexity and carry the reader through connected ideas at a pace that feels considered. Then stop. Uniform length creates a drone the reader tunes out. Deliberate variation creates emphasis — a short sentence after a long one hits harder.
Don't hedge without cause. "This will take two weeks" — direct. "This could potentially take approximately two weeks" — nervous. Qualify only when uncertainty is real. When it is, be specific about what's uncertain: "The API migration is done; the auth changes depend on whether Legal approves the new scope by Friday."
MATCH THE CONTAINER
Email. Subject line is the summary. First sentence is the ask or the point. Body is supporting context only. One call to action.
README. What it is → install → use. No pitch. No "In today's world of..." First paragraph answers: what does this do and who is it for.
Slack / chat. State the thing. No preamble. Questions go first, context after: "Can we push the deploy to Thursday? The staging tests aren't passing yet."
Cold outreach. Their problem first. Your relevance second. One specific ask. Under 100 words. No "I hope this email finds you well."
Technical docs. Assume reader has context. Show the thing, then explain it. Code examples before prose explanations. Be precise about types, parameters, return values.
Commit messages. What changed and why. Imperative mood: "Fix token expiry by caching expiry timestamp instead of issued-at." Subject under 72 characters.
Proposals / pitches. Problem → cost of the problem → solution → proof it works → ask. Frontload the pain. Numbers over adjectives.
SELF-EDIT
Fast pass before delivering. These are cuts, not additions.
Read each sentence. Does it carry new information the reader doesn't have yet? If it restates, summarizes, or previews — delete it.
Find every "It's worth noting," "Let me explain," "As mentioned earlier," "In summary." Delete them. The sentence after them is the real start.
Find hedges: "generally," "tends to," "it could be argued," "to some extent," "arguably." Is the uncertainty real and specific? Keep it and name the uncertainty. Is it just reflex? Cut it. State the thing.
Read only the first sentence of each paragraph, in sequence. Does that sequence alone tell the story? If it does, the structure is right. If it doesn't, restructure until it does.