Writing Clearly and Concisely

Overview

William Strunk Jr.'s The Elements of Style (1918) teaches you to write clearly and cut ruthlessly.

WARNING: elements-of-style.md consumes ~12,000 tokens. Read it only when writing or editing prose.

When to Use This Skill

Use this skill whenever you write prose for humans:

• Documentation, README files, technical explanations

• Commit messages, pull request descriptions

• Error messages, UI copy, help text, comments

• Reports, summaries, or any explanation

• Editing to improve clarity

If you're writing sentences for a human to read, use this skill.

Structure Principles

BLUF (Bottom Line Up Front)

U.S. military communication standard: put your conclusion first, then explain.

The rule: Your first sentence answers what you need and by when. The reader can act without reading further.

Structure:

• BLUF statement (1-2 sentences): the decision, action, or key point

• Supporting context: only what's needed to understand or act

Test: Can someone act on your message after reading only the first sentence?

Before: "I've been working on the marketing materials for the conference. The design team worked hard on the layout. Could you take a look when you get a chance?"

After: "I need you to approve the attached flyer by noon Friday. It's for the August conference."

Skip BLUF when:

• Delivering bad news (empathy first)

• Skeptical audience (persuade before concluding)

• Technical topics requiring foundation (explain concepts first—see below)

See: https://en.wikipedia.org/wiki/BLUF_(communication)

Explain Concepts Before Using Them

Information must be disclosed in the correct order. Never reference a term, concept, or acronym before you've defined it. If you use it, the reader must already understand it.

Limited Context Strategy

When context is tight:

• Write your draft using judgment

• Delegate a worker via teams with your draft and elements-of-style.md

• Have the worker copyedit and return the revision

If you REALLY REALLY need to preserve context, you can skip the full elements-of-style.md and instead use Orwell's rules:

• Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.

• Never use a long word where a short one will do.

• If it is possible to cut a word out, always cut it out.

• Never use the passive where you can use the active.

• Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.

• Break any of these rules sooner than say anything outright barbarous.

All Rules

Elementary Rules of Usage (Grammar/Punctuation)

• Form possessive singular by adding 's

• Use comma after each term in series except last

• Enclose parenthetic expressions between commas

• Comma before conjunction introducing co-ordinate clause

• Don't join independent clauses by comma

• Don't break sentences in two

• Participial phrase at beginning refers to grammatical subject

Elementary Principles of Composition

• One paragraph per topic

• Begin paragraph with topic sentence

• Use active voice

• Put statements in positive form

• Use definite, specific, concrete language

• Omit needless words

• Avoid succession of loose sentences

• Express co-ordinate ideas in similar form

• Keep related words together

• Keep to one tense in summaries

• Place emphatic words at end of sentence

Section V: Words and Expressions Commonly Misused

Alphabetical reference for usage questions

Bottom Line

Writing for humans? Read elements-of-style.md and apply the rules. Low on tokens? Delegate a worker via teams to copyedit with the guide.