B2 · Intermedio alto · 6 lecciones
Escribir documentación técnica en inglés
Escribir instrucciones, requisitos y changelogs que se entienden. Estas son las frases, la gramática y los ejemplos que usarás de verdad, explicados en español.
Instrucciones claras
Que cualquiera pueda arrancar el proyecto en diez minutos.
Frases clave
| Inglés | Español |
|---|---|
| Make sure you have Node 20 installed. | Asegúrate de tener instalado Node 20. |
| Run the following command to start the server. | Ejecuta el siguiente comando para arrancar el servidor. |
| Note that this step can take a few minutes. | Ten en cuenta que este paso puede tardar unos minutos. |
Gramática · Instrucciones en documentación
Make sure + frase · Run / Copy / Set + objeto · Note that + frase
Imperativo directo, un paso por línea. “Make sure” para requisitos previos y “Note that” para advertencias.
Copy the example file and make sure the port is free.
Copia el archivo de ejemplo y asegúrate de que el puerto está libre.
💡 Make sure (that) you have…, no “make sure to have” en este contexto (aunque también se oye).
Así lo dirías
Leo: A new dev joins tomorrow. Tell them how to set up the project.
Tú: First, clone the repo. Then run npm install to install the dependencies.
Para instrucciones, imperativo directo. “Must” va sin to y aquí sobra.
Requisitos formales
El lenguaje de las especificaciones y los RFC.
Frases clave
| Inglés | Español |
|---|---|
| Clients must send a valid token. | Los clientes deben enviar un token válido. |
| Requests should include a request ID. | Las peticiones deberían incluir un ID de petición. |
| The response may contain additional fields. | La respuesta puede contener campos adicionales. |
Gramática · Niveles de obligación
must (obligatorio) · should (recomendado) · may (opcional)
En especificaciones técnicas cada modal tiene un significado preciso, como en los RFC.
Clients must not cache this endpoint.
Los clientes no deben cachear este endpoint.
💡 Must not = prohibido. Don't have to = no es obligatorio. No son lo mismo.
Así lo dirías
Sarah: Explain the rules for using our public API.
Tú: Clients must use HTTPS, and they should send a User-Agent header.
Must sin to. Y en una especificación, “should” comunica “recomendado” con precisión, mejor que “can maybe”.
Explicar el funcionamiento
La pasiva hace que la documentación sea precisa y neutra.
Frases clave
| Inglés | Español |
|---|---|
| A new token is generated on every login. | Se genera un token nuevo en cada inicio de sesión. |
| Old sessions are deleted after 30 days. | Las sesiones antiguas se borran a los 30 días. |
| Errors are reported to Sentry automatically. | Los errores se reportan a Sentry automáticamente. |
Gramática · Pasiva para procesos
is / are + participio · is / are being + participio
Describe qué pasa, no quién lo hace. Para un proceso en curso: is being processed.
The file is being uploaded; it will be processed in the background.
El archivo se está subiendo; se procesará en segundo plano.
💡 Usa by solo si el agente es importante: errors are reported by the client SDK.
Así lo dirías
Leo: Explain how a password reset works in our system.
Tú: The user requests a reset. A link is then sent by email, and it expires after one hour.
Tercera persona con -s (requests, expires). Y la pasiva “a link is sent” suena más a documentación.
Escribir con precisión
Cambia expresiones vagas por datos concretos.
Frases clave
| Inglés | Español |
|---|---|
| The endpoint returns up to 100 items per page. | El endpoint devuelve hasta 100 elementos por página. |
| Response times are typically under 200 milliseconds. | Los tiempos de respuesta suelen estar por debajo de 200 milisegundos. |
| This only applies to accounts created after March. | Esto solo se aplica a las cuentas creadas después de marzo. |
Gramática · Precisión
up to · under / over · typically · only applies to
Sustituye “a lot”, “fast” o “sometimes” por cifras, límites y condiciones concretas.
Uploads are limited to up to 10 MB and typically take under two seconds.
Las subidas están limitadas a 10 MB como máximo y suelen tardar menos de dos segundos.
💡 Up to = como máximo. Typically = normalmente, en la mayoría de casos.
Así lo dirías
Sarah: Describe the limits of our free plan for the docs.
Tú: The free plan includes up to three projects and 1,000 API requests per day.
“Many but not too much” no informa. En documentación, cifras y límites concretos.
Changelog y release notes
Release notes que los usuarios sí leen.
Frases clave
| Inglés | Español |
|---|---|
| Added support for dark mode. | Añadido soporte para el modo oscuro. |
| Fixed a bug where exports were empty. | Corregido un error por el que las exportaciones salían vacías. |
| Deprecated the old search endpoint. | Marcado como obsoleto el antiguo endpoint de búsqueda. |
Gramática · Estilo de changelog
Added · Changed · Fixed · Removed · Deprecated + objeto
Cada línea empieza por un participio, sin sujeto. “Fixed a bug where…” explica qué pasaba.
Fixed an issue where users were logged out randomly.
Corregido un problema por el que los usuarios se desconectaban al azar.
💡 Deprecated = obsoleto pero todavía disponible. Removed = ya no existe.
Así lo dirías
Leo: Read out the release notes for version 2.4.
Tú: Added dark mode. Fixed a bug where exports were empty. Removed the old v1 API.
Las release notes van sin sujeto y con participio: Added, Fixed, Removed.
Un README de verdad
La puerta de entrada de cualquier proyecto.
Frases clave
| Inglés | Español |
|---|---|
| This library lets you validate forms in a few lines. | Esta librería te permite validar formularios en pocas líneas. |
| Contributions are welcome. | Las contribuciones son bienvenidas. |
| Please open an issue before submitting a PR. | Por favor, abre un issue antes de enviar un PR. |
Gramática · Estructura de un README
what it is → install → usage → configuration → contributing
Primera línea: qué hace y para quién. Luego, instalación y un ejemplo mínimo que funcione copiando y pegando.
This CLI lets you deploy in one command.
Esta CLI te permite desplegar con un solo comando.
💡 “Lets you + verbo” = te permite: lets you deploy in one click.
Así lo dirías
Sarah: Pitch your side project as the first lines of its README.
Tú: A CLI that lets you deploy any app in one command. Fast, simple and free.
“For to make” no existe. “Lets you + verbo” es la fórmula natural para decir qué permite hacer.