Documentación y READMEs en inglés
Un README en inglés no se escribe: se completa. Tiene seis secciones fijas, un tiempo verbal dominante y un puñado de estructuras que se repiten en todos los proyectos del mundo.
La documentación es el texto en inglés que más gente va a leer de todo lo que escribas, y el que menos inglés necesita. Es descriptiva, en presente, en segunda persona y sin metáforas: el registro más simple que existe.
Lo difícil no es el idioma. Es decidir qué va y qué no va, y no escribir el README que explica todo menos cómo arrancar el proyecto.
Las seis secciones
Casi todos los READMEs útiles del mundo tienen las mismas secciones en el mismo orden. Los títulos son estándar y conviene no inventarlos: la gente los escanea sin leer.
Plantilla
README
# Project name
One sentence saying what it does and for whom: "A CLI that turns invoice PDFs into structured JSON."
La primera línea es la que se copia en el buscador interno, en Slack y en el listado de repos. Si dice «this project» y nada más, obliga a leer el resto para entender de qué se trata.
## Requirements
Node 22+, Docker, and a Postgres 16 database.
Versiones concretas. «A recent version of Node» hace perder media hora a la primera persona que lo intenta.
## Getting started
Numbered steps, in the imperative: "1. Copy `.env.example` to `.env`. 2. Run `docker compose up -d`. 3. Run `npm run dev`."
Imperativo y una acción por paso. Es la sección que decide si alguien usa el proyecto o lo abandona.
## Usage
The two or three things people actually do, each with a copy-pasteable example.
Ejemplos reales, no `foo` y `bar`: un ejemplo que se puede pegar y correr enseña más que tres párrafos.
## Configuration
A table: variable, what it does, default value, required or not.
La tabla evita la pregunta más frecuente del repo, que siempre es «¿qué tengo que poner en esta variable?».
## How it works / Architecture
The decisions someone needs to know before changing the code, and the ones that are not obvious from reading it.
Va último a propósito: quien quiere usar el proyecto no necesita leerla, y quien va a modificarlo la busca igual.
Antes de seguir, predecí
El registro: presente, imperativo y «you»
La documentación técnica en inglés usa tres formas y casi ninguna más.
| Para qué | Forma | Ejemplo |
|---|---|---|
| Describir qué hace algo | Presente simple, tercera persona | The worker retries failed jobs every five minutes |
| Decirle al lector que haga algo | Imperativo | Run `npm install` before starting the server |
| Explicarle al lector qué le pasa a él | Segunda persona («you») | You'll need a Postgres database running on port 5432 |
| Una condición | If + presente | If the token is missing, the request returns 401 |
| Algo opcional | Can / optional | You can override the port with `PORT` |
| Algo obligatorio | Must / required | `DATABASE_URL` must be set |
| Una advertencia | Note / Warning + presente | Note: this deletes all rows in the table |
| Escrito así | Por qué falla | Mejor |
|---|---|---|
| This project was made for parsing invoices | Pasado y sobre el proyecto, no sobre lo que hace | Parses invoice PDFs into structured JSON |
| You should probably run the migrations | Ambiguo: ¿hay que hacerlo o no? | Run the migrations before starting the server |
| Simply run the script and everything will work | «Simply» no ayuda y suena condescendiente cuando no funciona | Run `npm run setup`. It creates the database and seeds it |
| We are going to explain the architecture | Anuncia en vez de decir | Architecture (y después la explicación) |
| For more information see the docs | Sin link no es una referencia | See [Configuration](./docs/configuration.md) |
Practicalo
Reescribilo
El encabezado de un README escrito como una presentación personal. Reescribilo para que alguien que cae en el repo sepa en diez segundos qué es y cómo arrancarlo.
# my-service
Hi! This is a project that I made some time ago to solve a problem we were having with invoices. It is written in Node and it uses a database. I hope it is useful! To use it you should probably install the dependencies and then simply run it.# invoice-parser Turns invoice PDFs into structured JSON. Used by the billing service to import supplier invoices without manual data entry. ## Requirements - Node 22+ - Postgres 16 ## Getting started 1. Copy `.env.example` to `.env` and set `DATABASE_URL`. 2. Run `npm install`. 3. Run `npm run dev`. The API listens on port 3000.
Una línea que dice qué hace y para quién, versiones concretas y tres pasos en imperativo que se pueden seguir sin pensar. El «hi», el «I hope it is useful» y el «simply» no le sirven a nadie.
# invoice-parser Turns invoice PDFs into structured JSON. npm install cp .env.example .env npm run dev
Para una herramienta chica, la versión mínima: una línea y el bloque de comandos. Es mejor un README de cinco líneas correcto que uno de cinco secciones a medio escribir.
Las dos versiones arrancan igual: una oración en presente que dice qué hace. Es la línea que más se lee de todo el repositorio.
documentation
/ˌdɒkjʊmenˈteɪʃn̩/ · suena como dokiumentéishon
Error común: acentuar «documentéishon» en la sílaba equivocada: el acento va en «tei»
variable
/ˈveəriəbl̩/ · suena como vériabol
Error común: decir «variáble» a la española
default
/dɪˈfɔːlt/ · suena como difólt
Error común: decir «défolt», acentuando la primera sílaba
required
/rɪˈkwaɪəd/ · suena como rikuáierd
Error común: decir «rekuíred»
usage
/ˈjuːsɪdʒ/ · suena como iúsich, con s sorda
Error común: decir «iúsach» con z
El audio lo genera tu navegador con voz sintetizada: alcanza para orientarse, y una persona que habla inglés lo dice mejor.
Lo que preguntan sobre esto
Cierre
Autoevaluación
¿Lo entendiste?
Práctica