Changelogs vs Notas de Publicación: Comparación detallada

¿Qué es un changelog?

Un changelog -o registro de cambios- es un documento detallado que proporciona una visión general de todos los cambios, actualizaciones, mejoras y correcciones realizadas en un producto de software a lo largo del tiempo.

Suele estar en orden cronológico inverso, mostrando los cambios más recientes en la parte superior de la página y las versiones anteriores del producto hacia el final de la misma.

Podría ser así:

O así:

Depende de ti anunciar (o no) tus próximas funciones o los proyectos en los que está trabajando actualmente tu equipo de desarrolladores. Dependiendo de tus productos/servicios y de tu base de usuarios, también puede cambiar el tipo de sistema de etiquetado y categorización que utilices para tus entradas en el changelog.

Independientemente de estas diferencias estratégicas, un buen changelog siempre debe ser claro y organizado. Debe permitir a tu público navegar fácilmente para encontrar la información relevante. Pero hablaremos de lo que constituye un buen registro de cambios en las próximas secciones, así que no te preocupes por eso de momento.

¿Qué es una nota de publicación?

Similar a un changelog, una nota de publicación es un documento que proporciona información sobre nuevas funciones, mejoras del producto y actualizaciones importantes.

Sin embargo, a diferencia de las entradas del registro de cambios, que incluyen hasta las correcciones de errores más pequeñas, las notas de la versión sólo incluyen, en su mayoría, los cambios significativos y las principales mejoras de funciones que probablemente repercutan en la experiencia del usuario.

Las notas de la versión también son más fáciles de usar y de leer, ya que están libres de jerga técnica. También se apoyan en elementos visuales, como vídeos o capturas de pantalla de la interfaz de usuario.

Las notas de publicación permiten más libertad en cuanto a estructura y diseño. Por eso difieren más entre sí que los diseños y estructuras relativamente similares de los changelogs.

Sin embargo, aquí tienes algunos ejemplos:

Como puedes ver, una nota de publicación no es necesariamente una comunicación unidireccional en la que compartes tus noticias y actualizaciones mientras tus clientes se limitan a escuchar (o leer). También puedes convertirla en una experiencia interactiva ofreciendo a los clientes la oportunidad de dar su opinión o una reacción rápida.

Las diferencias entre los changelogs y las notas de publicación

Aunque tanto las notas de publicación como los changelogs son medios para que los equipos de producto anuncien cambios o mejoras, difieren significativamente en su estructura, uso del lenguaje y otros aspectos.

Veamos cómo 🔎

Público objetivo

Los changelogs y las notas de publicación se dirigen a públicos diferentes. Mientras que los changelogs los leen sobre todo los desarrolladores y los usuarios técnicos, las notas de publicación se dirigen a un público más amplio, como los usuarios no técnicos y las partes interesadas.

En realidad, todas las demás diferencias entre las notas de publicación y los changelogs tienen su origen en esta diferencia principal.

Nivel de detalle

Los changelogs son básicamente listas exhaustivas de todos los cambios realizados desde la primera introducción del producto hasta hoy, lo que significa que incluyen hasta las correcciones y mejoras más pequeñas.

Mientras que las notas de la versión se centran en funciones clave, mejoras e introducciones que son relevantes para la experiencia general del usuario. Al ser para un público no técnico, no es necesario que incluyas pequeñas correcciones de errores si no son radicalmente importantes o ni siquiera perceptibles para el usuario medio.

Tono y estilo

Aunque las entradas del changelog suelen ser más detalladas en cuanto a los cambios que incluyen, no son necesariamente más explicativas o fáciles de entender.

Los Changelogs no suelen proporcionar instrucciones en profundidad ni casos de uso de las nuevas funciones. Describen la naturaleza del cambio, pero no son muy detallados y utilizan un lenguaje más técnico, ya que están dirigidos a los desarrolladores.

En cambio, las notas de publicación suelen ser más explicativas e instructivas. Utilizan un lenguaje más claro, conciso y fácil de usar, y a menudo incluyen ejemplos de casos de uso, ventajas y explicaciones adicionales.

El objetivo de un registro de cambios es informar a un desarrollador o usuario técnico sobre un cambio, sin motivarle necesariamente para que actúe.

En cambio, una nota de publicación no sólo informa a los usuarios sobre un cambio, sino que también les anima a actuar, como probar una nueva función. Por lo tanto, las notas de publicación suelen incluir desencadenantes de motivación, como propuestas de valor e instrucciones.

Formato y estructura

Los changelogs suelen estar formateados en orden cronológico inverso. En cambio, las notas de la versión están estructuradas para destacar primero las actualizaciones más importantes.

A menudo se clasifican por nuevas funciones, mejoras y correcciones de errores para facilitar su lectura. Los changelogs también incluyen un gran número de detalles técnicos, como números de versión, números de incidencia, fechas de publicación, fragmentos de código, etc.

Aunque todo esto también puede estar disponible en una nota de publicación, la mayoría de las veces no se incluye para no abrumar a los usuarios con demasiados detalles técnicos y se mantiene sólo en los registros de cambios.

Uso de elementos visuales

Otra diferencia importante entre los changelogs y las notas de publicación es el uso de elementos visuales, como capturas de pantalla de la UI o vídeos explicativos y tours del producto.

Aunque algunas empresas, como Mixpanel, incorporan elementos visuales -incluso vídeos- en sus changelogs, no es muy habitual añadir GIF, capturas de pantalla o vídeos de tours del producto a las entradas de los changelogs (pero vemos muchos fragmentos de código, si quieres contarlos también como elementos visuales).

Sin embargo, como las notas de la versión van dirigidas a usuarios no técnicos, suelen incorporar muchos elementos visuales para ayudar a los alumnos visuales a comprender el aspecto y el funcionamiento de la nueva función.

Los mejores casos de uso de los changelogs y las notas de publicación (+ ejemplos)

Todas estas diferencias entre los changelogs y las notas de publicación no implican que uno sea perfecto y el otro terrible. Más bien, hacen que cada una sea adecuada para diferentes casos de uso, que pueden enumerarse así 👇🏻

Los changelogs sirven para:

• Seguimiento del historial del proyecto y de los cambios en el código.
• Proporcionar información detallada a desarrolladores y equipos técnicos.
• Crear un punto de referencia para los equipos internos, como los equipos de apoyo.
• Mantener la transparencia y mantener informadas a las partes interesadas.  

Las notas de publicación sirven para:

• Anunciar nuevas funciones y actualizaciones a un público general.
• Destacar los casos de uso y las propuestas de valor a los usuarios finales.
• Animar a los usuarios a probar una nueva función o integración.
• Crear un punto de referencia para los equipos internos, como los equipos de ventas de éxito del cliente y de marketing.
• Comunicación con los usuarios finales y recopilación de opiniones tras las versiones

Veamos algunos ejemplos reales de estos casos de uso 👀.

1- CoScreen explica por qué los usuarios deberían probar su nueva función

CoScreen es una herramienta de colaboración para compartir pantallas creada específicamente para equipos de desarrollo de productos y equipos de ingeniería.

Y aquí tienes una nota de prensa de CoScreen:

Ahora bien, como CoScreen es una herramienta SaaS para desarrolladores, incluso sus notas de publicación tienen jerga técnica. Pero sigue siendo una nota de publicación y no una entrada en el changelog.

¿Sabemos cómo?

Porque no se trata simplemente de anunciar: "¡Eh, hemos lanzado CoTerm Beta!" y pasar a otros cambios del producto. En lugar de eso, ofrece motivaciones a los usuarios para animarles a probar la función.

⚠️ Así que, aunque tu base general de clientes esté formada por desarrolladores y programadores que puedan entender tus entradas del changelog, sigues necesitando notas de publicación junto con un registro de cambios para comunicar tus propuestas de valor a tus usuarios.

2- Notion enumera (en pequeño o en grande) todos los cambios y actualizaciones

Notion es una de las herramientas más populares para tomar notas y trabajar.

Y este es su changelog:

Hay registros de cambios diseñados específicamente para anuncios de productos, con etiquetas, categorías y entradas independientes para cada actualización. Y luego están los changelogs diseñados para mantener un historial completo del producto a lo largo del tiempo.

Este es un ejemplo del segundo tipo de changelog.

Notion ofrece un informe muy detallado y minucioso de lo que ha conseguido su equipo de desarrolladores, documentando cada cambio, por grande o pequeño que sea.

¿Han añadido aclaraciones a la documentación del producto?

Va al registro de cambios.

3- Slack garantiza la transparencia resaltando las actualizaciones importantes

Tú conoces Slack. Y yo sé que tú conoces Slack.

Así que saltémonos la introducción y vayamos al changelog de Slack 🦘

El changelog de Slack funciona de forma similar al de Notion, listando primero las actualizaciones más recientes y las más antiguas más abajo en la página.

Pero lo que Slack hace de forma diferente es poner las actualizaciones importantes, como los cambios de política o las desapariciones, justo en la parte superior, en una sección llamada "Actualizaciones importantes". Así, aunque algo se anunciara en marzo o abril, si sigue siendo relevante, lo verás inmediatamente cuando abras el registro de cambios.

Así:

4- Miro primero aborda los puntos débiles de los clientes y luego ofrece soluciones

Miro es una herramienta de colaboración digital y pizarra que permite a las personas colaborar en diseños, presentaciones, mapas mentales y hojas de ruta.

He aquí un extracto de una de sus notas de publicación mensuales:

Lo que hace Miro aquí es dirigirse directamente a las necesidades insatisfechas de un determinado segmento de usuarios: las grandes empresas. Tras abordar sus puntos débiles, ofrece una solución a sus problemas y presenta su propuesta de valor.

Lo mismo puede decirse de la segunda nota sobre funciones. Miro demuestra que entiende a sus clientes y lo que necesitan, y su equipo de desarrolladores trabaja para garantizar su satisfacción y felicidad.

5- UserGuiding recoge las opiniones directamente en su página de actualizaciones de productos

UserGuiding es una herramienta de adopción de productos todo en uno que permite a los equipos crear flujos interactivos dentro de la aplicación, centros de recursos, encuestas a clientes y páginas de actualizaciones del producto.

Y este es el aspecto de su página de actualizaciones de productos:

• Etiquetas ✅
• Microcopia amigable ✅
• Comunicación bidireccional ✅

UserGuiding no sólo utiliza su página de actualizaciones de productos para publicar notas de la versión; también la utiliza para recoger opiniones (escritas o reacciones) de sus usuarios. Esto crea una oportunidad para tantear el terreno y comprometerse directamente con sus usuarios.

Puede ser complicado determinar con precisión qué opinión de usuario corresponde a una actualización o función concreta, especialmente cuando las empresas lanzan varios cambios en un periodo corto, como las actualizaciones mensuales.

Sin embargo, con este sistema, aunque las empresas pueden atribuir las opiniones de los usuarios a actualizaciones concretas, los usuarios pueden enviar solicitudes de funciones o dejar comentarios, ¡incluso de forma anónima!

👉🏻 Pruébalo tú mismo 👈🏻

Buenas prácticas para changelogs

Ahora que hemos visto algunos ejemplos y nos hemos familiarizado con los changelogs, hablemos de las prácticas que transforman unos registros de cambios mediocres en unos impresionantes.

Crea un sistema (y cúmplelo)

Un changelog no es un basurero de actualizaciones de productos.

Tanto si publicas los cambios y mejoras de tus productos como entradas separadas o como un documento interminable, necesitas un sistema.

Aquí tienes algunas sugerencias:

• Utilizar etiquetas y rótulos para clasificar tus entradas (nuevas funciones, correcciones de errores, mejoras de la UI, cambios en la API, etc.).
• Implementar funciones de búsqueda y filtro.
• Crear una plantilla lista para rellenar con números de versión, números de ticket, números de incidencia, autores, planes afectados, fecha de publicación, etc.
• Resaltar las actualizaciones importantes con formato como negrita o código de colores, o al principio del documento de entrada/registro de cambios.
• Archivar versiones antiguas.

Garantizar la claridad

Los changelogs sirven como documentación técnica dirigida principalmente a desarrolladores y usuarios técnicos. Aunque no es necesario explicar en profundidad cada término técnico, es esencial utilizar un lenguaje técnico preciso y proporcionar detalles específicos.

Por ejemplo, al introducir una actualización importante en el esquema de una base de datos, incluye instrucciones claras sobre los cambios en el esquema, los pasos de migración y cualquier posible impacto en las estructuras de datos existentes; o al actualizar una API, es útil incluir instrucciones detalladas sobre su implementación.

Puedes explicar estos detalles en cuadros de texto desplegables para mantener tu changelog organizado y fácil de hojear.

Si te parece que no caben todas las instrucciones y explicaciones en un cuadro de texto desplegable (o si puedes, pero sería ineficaz), puedes crear guías de instrucciones separadas en tu base de conocimientos o artículos de ayuda y enlazarlas a tu changelog.

También puedes incorporar elementos visuales y fragmentos de código.

Utiliza integraciones de control de versiones

Si no quieres trabajar con una plantilla de changelog detallada -o utilizar una herramienta de changelog de terceros-, pero aun así quieres comunicar los cambios técnicos y las mejoras de funciones a otros desarrolladores, puedes automatizar tu registro de cambios vinculándolo con los commits de Git.

Cuando realices cambios en tu código base -como corregir errores, añadir nuevas funciones o mejorar las existentes- los mensajes de confirmación rellenarán automáticamente tu changelog y documentarán cada actualización en tiempo real.

Ahora bien, esta integración no proporciona ninguna explicación o descripción adicional, aparte de los propios cambios.

Así que sigues necesitando escribirlos si quieres que tu changelog sea un registro útil y provechoso. Sin embargo, sigue siendo útil, ya que no necesitas volver atrás y enumerar manualmente todos los cambios que ha hecho tu equipo en ese día/semana/mes/trimestre.

Así que es un buen punto de partida, digamos.

Buenas prácticas para las notas de publicación

Esto es lo que puedes hacer para mejorar tus notas de publicación 👇🏻

Personaliza el contenido

Las notas de la versión incluyen poca o ninguna jerga técnica (a menos que tus clientes sean únicamente desarrolladores, como en el caso de CoScreen). Sin embargo, los usuarios no técnicos no son todos iguales. La gente de producto, la gente de ventas y la gente de marketing hablan un lenguaje diferente. Así que, dependiendo de tu propia base de usuarios, adapta el contenido y el lenguaje.

Destaca la propuesta de valor

Recuerda que no sólo estás comunicando tu nueva función; estás abordando una necesidad del usuario y ofreciéndole una solución. Por tanto, es importante que hables el mismo idioma que tus usuarios al redactar tus notas de publicación, no sólo en un sentido técnico, sino también en términos de necesidades y expectativas.

Al igual que debes evitar un lenguaje demasiado técnico, también debes evitar un tono vendedor. Utiliza un lenguaje sencillo. No es un documento exclusivamente técnico, ni tampoco un discurso de venta, así que encuentra un término medio.

En una nota de publicación, puedes incluir:

• Breve descripción de las nuevas funciones,
• Casos prácticos/ ventajas,
• Necesidades insatisfechas de los clientes (que se cubrirán con estas nuevas funciones).

Hazlo digerible

En función de tus estrategias de producto, puedes publicar notas de publicación mensuales, trimestrales o siempre que lances una nueva actualización. La longitud de tus notas de publicación puede variar en función del momento y la complejidad de tus nuevas funciones. Sin embargo, debes mantenerlas tan breves y fáciles de entender -y leer- como sea posible.

También debes idear estrategias de formato para no agonizar a tus usuarios, sobre todo si piensas publicar notas de publicación extensas.

Puedes:

• Utilizar encabezamientos, resúmenes, viñetas y emojis,
• Incorporar capturas de pantalla y vídeos de tour del producto para funciones complejas,
• Utilizar enlaces a artículos de ayuda o guías prácticas para obtener detalles técnicos

Puntos clave

• Los changelogs ofrecen un registro histórico exhaustivo para el público técnico, mientras que las notas de la versión proporcionan un resumen accesible de las actualizaciones para una base de usuarios más amplia.
• Ambos documentos son esenciales para mantener la transparencia, garantizar una comunicación eficaz y mejorar la experiencia general del usuario.
• Ambos son valiosos puntos de referencia para los equipos internos. Los changelogs, centrados en la corrección de errores y las implementaciones técnicas, sirven como puntos de referencia para equipos como los de atención al cliente y éxito. Mientras que las notas de la versión, con sus explicaciones detalladas y propuestas de valor, son puntos de referencia para equipos como los de ventas y marketing.

Los changelogs utilizan lenguaje técnico y suelen estructurarse como listas concisas sin apenas explicaciones. Las notas de la versión utilizan un lenguaje narrativo y destacan los cambios significativos, sus ventajas para el usuario y los casos de uso con explicaciones y ejemplos claros y detallados.