Cómo escribir release notes que la gente lea

Para escribir release notes que la gente lea de verdad: una entrada por cambio visible, la capacidad nueva del lector primero, una línea fija con versión y fecha, y un solo enlace a la página que lo explica. Lo bastante cortas para leerlas en un ascensor. Una release note es un anuncio, no un segundo registro de cambios.

Casi todas las release notes fallan por una razón aburrida. Cuentan lo que hizo el equipo, en el orden en que lo hizo, con los nombres internos del equipo. El lector solo quiere saber una cosa: ¿puedo hacer hoy algo que ayer no podía? Escribe para esa persona y el formato casi se coloca solo.

Por qué las release notes acaban pareciendo un registro de cambios

Un registro de cambios es una lista continua. Una release note es el anuncio corto de una versión concreta. Se mezclan porque las dos se escriben después del mismo despliegue, por la misma persona, a partir de la misma lista de tareas. En cuanto esa lista se convierte en el guion, el anuncio se transforma en un diario de implementación.

Keep a Changelog lo resume en una frase: el registro de cambios es para personas, no para máquinas, y volcar mensajes de commit no cuenta (keepachangelog.com, consultado el 2026-10-18). La misma prueba vale para las release notes. Si una entrada solo tiene sentido para quien ya conoce el nombre interno del servicio, no está lista para el lector.

Un cambio que el usuario no ve suele ir al registro, no a la release note.

Las cuatro partes de una entrada de release notes

Cada cambio visible responde a cuatro preguntas en este orden: qué cambia, a quién afecta, qué tiene que hacer el lector y dónde leer más. Las dos primeras caben en una frase. La tercera muchas veces es «nada», y está bien. La cuarta es un enlace, no un párrafo de explicación.

El orden coincide con la forma de escanear. Se leen las primeras palabras de cada línea, se para en la que parece relevante y luego se decide si se hace clic. Una entrada que empieza por «Hemos refactorizado el servicio de facturación» no da ningún motivo para parar.

La plantilla que puedes copiar

Todo el entregable está aquí. La cabecera fija va arriba y después un bloque por cambio. Puedes quitar las etiquetas cuando tu público ya conozca el formato, pero no cambies el orden.

## 2026-10-18 · v1.4.0

**Nuevo**
- Exportar un perfil de producto a CSV. Disponible en todos los planes. No hay que activar nada.
  Detalles: /help/export-product-profile

**Mejorado**
- Los envíos a directorios guardan la fecha del último control. Sin acción.

**Corregido**
- La lista de lanzamiento ya no se reinicia al refrescar la página.

**Acción necesaria**
- Si conectaste un dominio propio antes del 1 de octubre, revisa el registro DNS.
  Detalles: /help/custom-domain

Dos reglas hacen que la plantilla aguante una versión real. La versión y la fecha van en la cabecera, no en cada línea. Cada entrada empieza por la capacidad del lector, no por el nombre del componente. «Exportar un perfil de producto a CSV» pasa. «Exportador CSV v2» no pasa.

Qué incluir y qué dejar fuera

Decide por el tipo de cambio, no por el tamaño del diff. Un arreglo de una línea que cambia lo que ve el lector entra. Una semana de trabajo interno que no cambia nada visible, no.

Un cambio de precio merece su propia nota porque cambia una decisión, no una pantalla. Enterrado en una lista pasa desapercibido, y el mensaje de soporte que llega después cuesta más que la nota extra.

En seguridad hay que decidir. Di qué hacer y qué versiones están afectadas. No publiques una receta de reproducción antes de que el arreglo haya llegado a todo el mundo. Si no puedes contar la segunda parte sin riesgo, cuenta menos y enlaza al aviso.

Reutilizar una release note en varios canales

Escribe la nota una vez y cambia el envase, no los hechos. La página del registro conserva todas las entradas. El mensaje dentro de la app conserva las de la pantalla actual. El correo conserva la entrada que cambia una decisión. Un directorio o una comunidad conserva la entrada que un lector nuevo entiende sin contexto.

En este paso es donde muchos equipos crean dos versiones de la verdad. Mantén la fecha y el número de versión idénticos en todas partes. Si el registro dice que la v1.4.0 salió el 18 de octubre, el correo no puede decir «esta semana» sin dar la fecha en algún sitio.

Dónde se rompen las release notes

Los fallos son previsibles y cada uno tiene un síntoma visible.

1. La nota es un registro de commits. Síntoma: nombres de servicios, ramas o tickets. Arreglo: reescribir desde la pantalla del lector hacia atrás.
2. Cada versión es «emocionante». Síntoma: los mismos tres adjetivos cada mes. Arreglo: borra el adjetivo y quédate con el verbo. Una nota sobria sigue siendo útil.
3. La nota llega después que el buzón de soporte. Síntoma: los usuarios preguntan por qué cambió algo antes de que se publique. Arreglo: publica con la versión, no después de las quejas.

Hay un cuarto fallo más difícil de ver: anunciar un cambio que nadie encuentra. Si la capacidad nueva está detrás de tres menús y la nota no dice dónde, es exacta e inútil. Añade la ruta, una captura o un enlace a la página que muestra la ruta.

Lo que no hemos medido

No hemos medido si unas mejores release notes cambian la retención, las mejoras de plan o el volumen de soporte. Ningún estudio público que podamos verificar aísla ese efecto, y no vamos a inventar uno. Lo que sí podemos decir es más estrecho: una nota escrita en el orden del lector se escanea mejor, y una entrada con línea de acción genera menos respuestas de «¿y ahora qué hago?». Es un juicio de escritura, no un resultado medido.

Preguntas frecuentes

¿Cuánto debe medir una release note?

Lo que exijan los cambios visibles, y nada más. Un cambio puede ocupar tres líneas. Diez cambios pueden caber en una pantalla si cada entrada es una frase. Si la nota necesita un índice, probablemente sea una página de registro, no un anuncio.

¿Hay que escribir una nota por cada despliegue?

No. Escribe una por cada versión que un lector pueda notar. Un despliegue sin cambios visibles no necesita nota. Un despliegue que cambia el texto de un botón sí, porque alguien lo notará y se preguntará si lo recordaba mal.

¿Las release notes ayudan al SEO o a las respuestas de IA?

Pueden ayudar, pero no por la palabra «release». Una página fechada que nombra la función, el plan y la acción es una buena página de destino para quien busque esa función más adelante. Una página de números de versión sin nombres de funciones da muy poco a un buscador. No hemos medido ninguna ganancia de citas, así que es un argumento estructural, no una promesa.

¿Dónde se publica la nota?

Una URL canónica por versión, con la fecha en la página y en la URL si el sistema lo permite. Republica la versión corta en los canales que la necesiten, pero conserva la página canónica como destino del enlace. Cinco copias con cinco fechas son cinco fuentes de verdad.

Siguiente paso

Coge la última versión publicada y reescribe una entrada con el orden de cuatro partes. Si queda más corta y más concreta, la plantilla funciona. Si se alarga, probablemente estás explicando la implementación en lugar de la capacidad.

Las release notes son una entrada del flujo de contenido. La misma reescritura centrada en el lector vale para el brief de contenido que le pasas a un redactor, y la misma lógica de canales vale cuando adaptas una descripción de producto a cada canal. Cuando la nota esté lista, publícala donde vive el producto y mantén el flujo de contenido en un solo sitio para que la próxima versión no empiece en blanco.