---
name: writing-for-understanding
description: "Guidelines for writing clear, plain-language prose that readers understand on the first read. Use this skill whenever writing or editing internal business communication or documentation — emails, memos, reports, proposals, status updates, internal announcements, meeting notes, help articles, docs, READMEs, and messages to colleagues. Trigger it even when the user only says \"write this up,\" \"draft an email,\" \"tighten this,\" \"make this clearer,\" \"explain this,\" or shares a rough paragraph to improve, without mentioning \"plain language\" or \"clarity\" directly. Do not use this skill for marketing, advertising, or public-facing web or homepage copy — that writing needs a persuasive voice this skill deliberately strips out."
---

# Writing for Understanding

Write so a reader understands you correctly on the first read.

These guidelines apply to internal business communication and documentation: an email to a colleague, a status update, a report or proposal, an internal announcement, meeting notes, a help article, and technical documentation. The goal stays the same across all of them — the reader gets your meaning once, without rereading or guessing.

This skill is for writing meant to inform and to be acted on. It is not for marketing or public web copy, which needs a persuasive voice that these rules deliberately strip out.

A few rules near the end apply mainly to technical documentation. They sit in their own section so they stay out of the way when you write anything else.

## Core checks

Run every paragraph through these questions:

- Does the person or thing doing each action appear as the subject? (active voice)
- Is each verb in present tense, unless the future or a condition is the actual point?
- Does each sentence carry one idea?
- Is the paragraph about 150 words or fewer, in three to eight sentences?

## Short is not the same as clipped

Plain and short do not mean casual or abrupt. Cut words that add nothing, but keep the words that carry tone and meaning.

Two habits protect the reader here. First, match the register the reader expects: a company-wide announcement stays professional, while a quick note to one teammate can relax. Second, write complete sentences. A fragment like "Questions?" saves two words, but it reads as terse and can shift the tone of an otherwise professional message. Write "Reach out if you have any questions" instead.

## 0. Clarify Vague Pronoun references

Make it clear what a pronoun is referring to. T

| Write | Not |
|---|---|
| One function performs all the actions. | One thing does it all. |

## 1. Use active voice

Make the actor the subject. Passive voice hides who does what.

| Write | Not |
|---|---|
| The team shipped the release on Friday. | The release was shipped on Friday. |
| Finance approves every invoice over $5,000. | Every invoice over $5,000 must be approved. |
| The client sends a request to the server. | A request is sent to the server. |

Spot passive voice by a "to be" verb (is, was, were, are, been) followed by a past participle (often ending in "-ed"). When the actor is missing, write it back in.

Use passive voice only when the actor truly doesn't matter: "The office closes at 6 p.m." or "Requests are limited to 100 per minute."

## 2. Use present tense

Present tense states facts directly. Save the future or conditional tense for behavior that is actually future or conditional.

| Write | Not |
|---|---|
| The report covers last quarter's results. | The report will cover last quarter's results. |
| Clicking Save updates the record. | Clicking Save will update the record. |
| This endpoint returns 404 when the resource is missing. | This endpoint will return a 404 if the resource does not exist. |

## 3. Unhide your verbs

A hidden verb is a verb turned into a noun, often ending in -tion, -sion, -ment, or -ance. It forces a weaker verb around it and adds words.

| Write | Not |
|---|---|
| We decided to delay the launch. | We made a decision to delay the launch. |
| Please review the draft. | Please conduct a review of the draft. |
| The tool validates the file. | The tool performs validation of the file. |

Look for a "-tion/-ment/-sion/-ance" noun sitting between "the" and "of" — that's the pattern. Turn it back into a verb.

## 4. One idea per sentence

Split a condition from its consequence instead of merging them:

> If you miss the deadline, the system moves your request to the next cycle.

Not:

> If you miss the deadline, which is the last business day of the month, the system will move your request to the next cycle and notify your manager by email.

When a sentence runs long or stacks several clauses, break it into two.

## 5. Keep paragraphs and sections short

Cap each paragraph at about 150 words and three to eight sentences. Give each paragraph one topic, and open it with a sentence that states that topic. Add headings freely — readers skim, and specific headings help them find the right part without reading everything.

## 6. Choose familiar words

Prefer common, everyday words. Reach for a longer or more technical word only when a simpler one would lose real meaning.

| Write | Not |
|---|---|
| use | utilize |
| start | commence, initiate |
| help | facilitate |
| about | regarding, pertaining to |
| if | in the event that |
| because | on the grounds that |
| enough | sufficient |
| buy | purchase |

## 7. Phrase things as what is possible, not what can't be done

State what is true or allowed. A positive sentence is easier to follow than a negative one, and stacked negatives force the reader to untangle them.

| Write | Not |
|---|---|
| Only admins can delete a workspace. | Non-admins may not delete a workspace. |
| Submit the form by Friday to stay in this cycle. | If you do not submit the form by Friday, you will not remain in this cycle. |
| Keep the token valid for at least 5 minutes. | The token must not be invalid for less than 5 minutes. |

Watch for "unless," "except," "fail to," and "other than" stacked after a negative, and rewrite the sentence positively.

## 8. Cut "simply," "just," and "easy"

Words like "simply run this" or "it's easy to set up" hide the effort a task actually takes. When the task turns out to be hard, the reader feels the writing misled them. Describe the step plainly and let the reader judge how easy it is.

| Write | Not |
|---|---|
| Clear your cache, then sign in again. | Simply clear your cache and try again. |
| Fill in the three required fields to submit. | Just fill in a few quick fields and you're done. |

## 9. Break up stacked nouns

Three or more nouns in a row force the reader to guess which words are the real nouns and which act as adjectives.

| Write | Not |
|---|---|
| settings for request timeouts | request timeout configuration settings |
| the plan for onboarding new customers | new customer onboarding process plan |

Cut a word, or add "for" or "of" to show how the words relate.

## 10. Avoid invented compound adjectives

Don't invent a modifier on the spot, like "request-aware" or "results-driven," because it makes the reader decode a relationship you could have stated in plain words.

| Write | Not |
|---|---|
| a cache that's aware of the request | a request-aware cache |
| a team focused on results | a results-focused team |
| a report tailored to each client | a client-tailored report |

Keep a compound only when it's already a standard term readers know (real-time, open-source, user-friendly, full-time).

## 11. Define abbreviations, and use few of them

Spell out an abbreviation the first time you use it: "annual recurring revenue (ARR)." Skip this for abbreviations nearly everyone knows in context (for a general audience, FAQ or PDF; for developers, API, URL, or JSON). Introduce only a few new abbreviations per piece — when they pile up, spell the rest out or give them a short plain name.

## 12. Show a concrete example

For anything non-obvious — a process, an edge case, a calculation, an error — show a real example instead of describing it in the abstract. A sample message, a filled-in form, a specific number, or a short code snippet lands faster than an abstract description. Write "for example" or "such as," not "e.g." or "i.e."

## 13. Write link text that describes the destination

Name where a link goes. Skip "click here" and "read more."

| Write | Not |
|---|---|
| See the onboarding checklist. | Click here for onboarding. |
| Read the full pricing policy. | Read more. |

## Self-review checklist

- [ ] The register matches the reader; short did not turn clipped or casual
- [ ] Every sentence is complete — no fragments used to save words
- [ ] Every sentence has a clear actor doing something
- [ ] Verbs are present tense unless the future or a condition is the point
- [ ] No hidden verbs
- [ ] Each sentence carries one idea
- [ ] Paragraphs run about 150 words or fewer, three to eight sentences
- [ ] Common words replace fancy ones where meaning allows
- [ ] Sentences state what is possible, not stacked negatives
- [ ] No "simply," "just," or "easy" hiding real effort
- [ ] No stacked nouns of three or more words
- [ ] No invented compound adjectives — only established ones (real-time, open-source)
- [ ] Abbreviations are either widely known or defined once, and kept few
- [ ] Anything non-obvious has a concrete example
- [ ] Link text names its destination

## For technical documentation

These extra rules matter most in developer-facing docs — READMEs, API references, guides, changelogs, and error messages. Skip them for other writing.

**State requirements with must / should / may.** In specs and reference docs, these words carry precise meaning:

- **must**: required
- **must not**: prohibited
- **should**: recommended, not required
- **may**: optional

Avoid "shall." It blurs the line between an obligation and a prediction.

**Show a request/response pair for real behavior.** For auth flows, error handling, and edge cases, show a concrete request and its response, or a runnable snippet, rather than describing the behavior in prose.

**Fix the docs before adding an FAQ.** A well-organized page beats an FAQ. Check whether each FAQ question points to a gap in the main content, and fill that gap first. If you keep an FAQ, base it on real user confusion, keep answers short, and don't repeat what the main docs already say.