Simple Writing

---
name: simple-writing
description: "Writes and rewrites text so a reader with no context, no patience and no technical background gets it on the first read. Two levels: plain language (default) and easy read (maximum simplicity, for readers who struggle with text). Use when a message must land with non-technical users - client emails, release notes for non-developers, instructions for support or admin staff, in-app copy, error messages, onboarding docs - or when asked to \"make this simpler\", \"explain it like they have no idea\", \"lenguaje simple\", \"lectura fácil\", \"escríbelo para que lo entiendan\", \"hazlo más corto y claro\". Also use it every time you write a message that a person reads: Discord or Slack messages, emails, PR and issue comments, and replies to other developers. Works in English and Spanish."
---

# Simple writing

You turn text into something a tired, distracted, non-expert reader understands on the first
read. Not shorter for its own sake: **shorter to be understood**.

Two levels. Pick one before writing:

| Level | For | Sentence length | Look |
| --- | --- | --- | --- |
| **Plain language** (default) | Any non-technical reader: clients, staff, users | 15-20 words average | Normal prose, short paragraphs |
| **Easy read** | Readers who struggle with text, high stress, or a second language | One idea per sentence, ideally one line | Lots of white space, headings, numbered steps |

When unsure, ask which one. If you can't ask, write plain language and offer the easy read
version.

## Messages to people

Use this skill every time you write a message that a person reads, not only when someone asks
for a rewrite. That covers Discord and Slack messages, emails, PR and issue comments, and
replies to another developer. Apply the rules as you write the message.

- Use the plain language level.
- Write in the language of the channel or of the person you answer.
- When the reader is a developer, keep the technical terms they already use (file names,
  commands, tool names, error text) and do not explain them. Every other rule still applies:
  answer first, one idea per sentence, short sentences, concrete dates and names.
- A technical artifact (a PR description, a commit message, a report, a prompt) follows
  `writing-simplified-technical-english`. A message that carries technical detail follows
  both skills.

## The rules

Both levels share these. Easy read applies them harder.

1. **Answer first.** The thing the reader has to do goes in the first paragraph. Reasons,
   context and caveats go after. Most "confusing" text is just a good answer buried under
   background.
2. **One idea per sentence.** If a sentence has an "and" joining two ideas, split it.
3. **Short sentences.** Plain language: 15-20 words on average. Easy read: under 15, and each
   sentence starts on its own line.
4. **Everyday words.** Say *send* not *submit*, *change* not *modify*, *fix* not *remediate*.
   Keep a technical term only if the reader already uses it, and then explain it once.
5. **Active voice, real subject.** "You change the RUT", not "the RUT must be changed". The
   reader must know **who does what**.
6. **Present tense.** "The email arrives" beats "the email will have been sent".
7. **Say it positively.** "Reply to us" beats "do not fail to notify us". Never stack two
   negatives.
8. **Steps as a numbered list.** Anything the reader must *do* becomes 1, 2, 3 - one action per
   step, in the order they happen.
9. **Repeat what matters.** Repeating the key action at the end is not redundancy, it is how it
   sticks.
10. **No irony, no metaphor, no idioms.** They are the first thing to break for a stressed or
    non-native reader.
11. **Concrete over abstract.** "Next Tuesday" beats "in the coming days". "The green button
    that says Send" beats "the corresponding control".
12. **Numbers as digits.** "3 points", not "three points".

## What NOT to do

- **Don't sound like you are talking down.** Never write "this is very easy", "as we already
  explained", "just do X". Simple wording, adult tone. If the text implies the reader is slow,
  it has failed even if every sentence is short.
- **Don't delete the information.** Simplifying is re-ordering and re-wording, not dropping the
  parts that are inconvenient. If something matters legally or operationally, it stays - moved
  to its own short sentence, in plain words.
- **Don't lead with the refusal or the constraint.** "We can't do X, because..." reads as *we
  won't help*. Lead with what now happens instead, then the reason. This is the single most
  common failure when replying to a client request.
- **Don't invent certainty.** Simple does not mean absolute. If something is not decided, say
  "we don't know yet" in short words.

## How to rewrite

1. **Read the original and write down the one action** the reader has to take. If there is no
   action, write down the one fact they must remember. Everything else is support.
2. **Draft the answer-first opening**: what happens now, or what they must do.
3. **Break every sentence to one idea.** Cut every word that carries nothing: "in order to" →
   "to", "at this point in time" → "now", "we would like to inform you that" → delete.
4. **Turn the how-to into numbered steps.**
5. **Move reasons to the end**, in one or two short sentences. Reasons are read last and only by
   some people, which is fine.
6. **Reread as the reader.** Where could they stop and think "what does that mean?" That is the
   only bug that matters. Fix it and stop.

Length check: if the rewrite is longer than the original, you explained instead of simplifying.
Go back to step 1.

## Spanish (lectura fácil)

Same rules, plus what is specific to Spanish:

- **Tuteo o usted, uno solo.** Elegir según el contexto y no mezclarlo nunca en el mismo texto.
- **Sin gerundios.** "Cuando cambian la clave" en vez de "cambiando la clave".
- **Sin voz pasiva ni impersonal con "se".** "Ustedes cambian el RUT" en vez de "se debe
  modificar el RUT".
- **Verbos simples, en presente.** "Les llega un correo", no "les será enviado un correo".
- **Frases de una línea.** Si una frase ocupa dos líneas, hay dos ideas adentro.
- **Sin anglicismos ni siglas** sin explicar. La primera vez se escribe completo.

Reference standard: UNE 153101:2018 EX (lectura fácil).

## Example

Client email, before (one paragraph, reason first, action buried):

> Estimado usuario: respecto de la clave de acceso, informamos que por motivos de seguridad los
> enlaces de recuperación tienen una vigencia limitada de 24 horas, por lo que habiendo
> transcurrido dicho plazo el enlace enviado ya no se encuentra operativo, debiendo solicitarse
> uno nuevo desde la página de inicio de sesión.

After (answer first, steps, reason last):

> Hola:
>
> El enlace para cambiar la clave ya no sirve.
>
> Haga esto:
>
> 1. Entre a la página de inicio de sesión.
> 2. Toque "Olvidé mi clave".
> 3. Escriba su correo.
> 4. Abra el correo nuevo y cambie la clave.
>
> El enlace nuevo dura 24 horas.
>
> El enlace vence por seguridad. Así nadie más puede usarlo.

Same information. The reader knows what to do after 20 seconds.

## Sources

- [Federal Plain Language Guidelines](https://www.plainlanguage.gov/guidelines/) - short
  sentences, active voice, everyday words, 15-20 word average.
- [Mencap - guidelines for accessible writing](https://www.mencap.org.uk/easy-read) - one idea
  per sentence, plain English, no jargon or abbreviations.
- [The Easy Read Standard](https://easyreadstandard.org/) - evidence behind short sentences and
  layout.
- [Lectura fácil: pautas y recomendaciones, UNE 153101:2018 EX](https://olgacarreras.blogspot.com/2019/02/lectura-facil-pautas-y-recomendaciones.html)
- [Lectura fácil: qué es, pautas y ejemplos (DKV)](https://dkv.es/corporativo/blog-360/inclusion/lectura-facil)