Cómo escribir release notes que la gente lea (guía LatAm)

Para escribir release notes que la gente lea: una entrada por cambio visible, primero la capacidad que gana el lector, una línea fija con versión y fecha, y un solo enlace al detalle. Si no se entiende en una pasada, está demasiado larga. Una release note es un aviso de una versión, no el registro completo.

El error más común no es de redacción. Es de orden. El equipo escribe en el orden en que trabajó y usa los nombres que usa puertas adentro. Del otro lado hay alguien que solo pregunta si ahora puede hacer algo que antes no podía. Si escriben para esa persona, la estructura se ordena sola.

Release notes no es lo mismo que changelog

El changelog acumula versiones. La release note anuncia una. Se confunden porque nacen del mismo despliegue y de la misma lista de tareas. Cuando la lista se vuelve el índice, el aviso termina siendo un diario técnico.

Keep a Changelog lo dice sin rodeos: el changelog es para personas, no para máquinas, y volcar mensajes de commit no sirve (keepachangelog.com, consultado el 2026-10-18). La prueba es la misma para una release note. Si una entrada solo la entiende quien conoce el nombre interno del servicio, todavía no está lista.

Lo que el usuario no puede ver, por lo general va al changelog y no al aviso.

Las cuatro partes de una entrada de release notes

Cada cambio visible contesta cuatro preguntas en este orden: qué cambió, a quién le toca, qué tiene que hacer y dónde ver más. Las dos primeras son una frase cada una. La tercera muchas veces es «nada». La cuarta es un enlace, no una explicación larga.

El orden sigue la lectura rápida. Se miran las primeras palabras de cada línea, se frena en la que parece propia y recién ahí se decide el clic. «Refactorizamos el servicio de facturación» no da motivo para frenar.

Plantilla para copiar y pegar

Este es el entregable completo. Cabecera fija arriba y un bloque por cambio. Si el público ya conoce el formato, pueden quitarse las etiquetas; el orden no se toca.

## 2026-10-18 · v1.4.0

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

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

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

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

Dos reglas mantienen la plantilla sana. Versión y fecha van en la cabecera, no repetidas en cada línea. Cada entrada arranca con la capacidad del lector, no con el nombre del componente. «Exportar un perfil de producto a CSV» sirve. «Exportador CSV v2» no.

Qué entra y qué queda afuera

La decisión depende del tipo de cambio, no del tamaño del diff. Un arreglo de una línea que cambia lo que se ve entra. Una semana de trabajo interno que no mueve nada visible queda afuera.

Un cambio de precio merece su propio aviso porque mueve una decisión, no una pantalla. Escondido en una lista pasa de largo, y el mensaje de soporte que llega después sale más caro que el aviso extra.

En seguridad hay que elegir. Digan qué hacer y qué versiones están afectadas. No publiquen una receta de reproducción antes de que el parche llegue a todos. Si la segunda parte no se puede contar sin riesgo, cuenten menos y enlacen al aviso oficial.

Una release note, varios canales

Escriban una vez y cambien el envase, no los hechos. La página del changelog conserva todo. El mensaje dentro de la app conserva lo de la pantalla actual. El correo conserva la entrada que cambia una decisión. La ficha de un directorio o un post de comunidad conserva lo que un lector nuevo entiende sin contexto.

Acá es donde suelen aparecer dos versiones de la verdad. Mantengan la fecha y el número de versión iguales en todos lados. Si el changelog 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 lugar.

Dónde se rompe el aviso

Los errores se repiten y cada uno deja una señal visible.

1. El aviso es un log de commits. Señal: aparecen servicios, ramas o tickets. Arreglo: reescribir desde la pantalla del lector hacia atrás.
2. Todo es «emocionante». Señal: los mismos tres adjetivos cada mes. Arreglo: sacar el adjetivo y dejar el verbo.
3. El aviso llega después del reclamo. Señal: la gente pregunta por qué cambió algo antes de que se publique. Arreglo: publicar junto con la versión.

Hay un cuarto error menos visible: anunciar algo que nadie encuentra. Si la capacidad está detrás de tres menús y el aviso no dice dónde, es correcto e inútil. Agreguen la ruta, una captura o un enlace a la página que la muestra.

Lo que no medimos

No medimos si unas mejores release notes cambian la retención, las mejoras de plan o el volumen de soporte. No encontramos un estudio público verificable que aísle ese efecto y no vamos a inventar uno. Lo que sí se puede afirmar es más acotado: una nota en el orden del lector se recorre más rápido, y una entrada con línea de acción genera menos respuestas de «¿y ahora qué hago?». Es un criterio de escritura, no un resultado medido.

Preguntas frecuentes

¿Qué tan larga debe ser una release note?

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

¿Hay que escribir una por cada despliegue?

No. Escriban una por cada versión que el lector pueda notar. Un despliegue sin cambios visibles no necesita aviso. Uno que cambia el texto de un botón sí, porque alguien lo va a notar y va a dudar de su memoria.

¿Sirven para SEO o para las respuestas de IA?

Pueden servir, 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 después. Una página de números de versión sin nombres de funciones le da muy poco a un buscador. No medimos ninguna ganancia de citas, así que es un argumento de estructura, no una promesa.

¿Dónde se publica?

Una URL canónica por versión, con la fecha en la página y en la URL si el sistema lo permite. La versión corta se replica en los canales que la necesiten, pero el enlace siempre vuelve a la página canónica. Cinco copias con cinco fechas son cinco fuentes de verdad.

Siguiente paso

Tomen la última versión publicada y reescriban una entrada con las cuatro partes. Si queda más corta y más concreta, la plantilla está funcionando. Si se alarga, probablemente estén explicando la implementación y no la capacidad.

Las release notes son una pieza del flujo de contenido. La misma reescritura centrada en el lector aplica al brief de contenido que le pasan a un redactor, y la misma lógica de canales aplica cuando adaptan una descripción de producto a cada canal. Cuando el aviso esté listo, publíquenlo donde vive el producto y mantengan el flujo de contenido en un solo lugar para que la próxima versión no arranque en blanco.