Cómo construir una página de changelog que la gente sigue

Una página de changelog vale la pena construirla cuando alguien volvería a ella. Esa es una vara más alta que simplemente tenerla, y es la vara en la que la mayoría falla: una página que existe, está enlazada en el footer, se actualiza a rachas y no la visita nadie salvo durante un incidente. Las decisiones que separan las dos se toman antes de escribir nada, y son sobre todo acerca de dónde vive la página y qué más se genera a partir del mismo contenido.

¿Qué es una página de changelog?

Es la lista pública y fechada de qué cambió en un producto, en una URL que os pertenece. Es una de cinco superficies donde pueden aparecer las mismas entradas, y la pregunta útil no es cuál elegir sino cuál es canónica y cuáles se generan a partir de ella.

Elegid una fuente canónica, publicad una vez, y generad el resto. Los equipos que mantienen la página y el widget por separado a mano acaban con dos textos que no coinciden, y la discrepancia la descubre un cliente.

¿Dónde debería vivir una página de changelog?

En vuestro propio dominio, en una ruta estable, con cada entrada direccionable individualmente. Las tres ubicaciones habituales son una ruta en el sitio principal, un subdominio, y una sección de la documentación. Una ruta en el sitio principal es la opción por defecto contra la que hay que argumentar, no a favor: hereda la autoridad del sitio, no necesita certificado ni DNS extra, y mantiene la página en la misma navegación que todo lo demás.

Un subdominio es la respuesta correcta cuando la página la sirve un sistema distinto del sitio de marketing y de otro modo estaríais haciendo proxy. El coste es que acumula autoridad por separado. Meter el changelog en los docs es correcto cuando el público son desarrolladores, por la razón que se cubre en changelog de API: el lector suele estar ya ahí.

Lo que importa más que la elección es que las entradas sean enlazables individualmente. La gente enlaza entradas en revisiones de incidentes y tickets internos, y una entrada que solo se puede enlazar como “el changelog, baja hasta ahí” acaba pegada como captura de pantalla en su lugar.

¿Qué necesita una página de changelog?

Cinco cosas, y en las dos primeras fallan la mayoría de páginas. Una entrada fechada por cambio, la más reciente primero. Una categoría o etiqueta por entrada para poder escanear por el tipo que interesa. Un permalink por entrada. Una vía de suscripción. Una búsqueda o filtro una vez que hay más de unas cincuenta entradas.

Todo lo demás es opcional. Las capturas de pantalla ayudan y cuestan mantenimiento. Los nombres de autor generan confianza en algunos productos y ruido en otros. Los números de versión importan a consumidores de una API y a casi nadie más. Keep a Changelog es una opción razonable por defecto para las etiquetas si no tenéis razón para inventar las vuestras, y su regla central es la que hay que conservar aunque descartéis el resto: el log es para humanos.

Agrupad por fecha en lugar de por versión cuando vuestro producto se publica de forma continua. Un lector que busca “esto fue antes o después de nuestro incidente del día nueve” busca una fecha, y una página organizada por número de versión le obliga a hacer cuentas.

¿Página o widget en la app?

Ambos, desde una sola fuente. La página es donde viven la búsqueda, los enlaces y el registro largo. El widget es cómo llegáis a la mayoría de usuarios que nunca visitarán la página, y funciona porque aparece en el producto que ya están usando.

El fallo del widget es la interrupción. Un badge que exige atención por cada entrada se descarta permanentemente en una semana, lo que os cuesta el canal para la entrada que sí importaba. Contad no leídas desde la última vez que el lector miró, sembrad el contador en silencio en la primera visita para que nadie sea recibido con un badge de un año de historial, y dejad que el lector lo abra en lugar de abrirlo por él.

¿Cómo se hace legible por máquinas una página de changelog?

Publicad las mismas entradas como feed. Un feed JSON es la opción de menor fricción para cualquiera que lo consuma en código, y un feed RSS es lo que espera un desarrollador que se suscribe en un lector. Ambos cuestan poco una vez que las entradas son datos estructurados en lugar de HTML escrito a mano, que es el argumento real para mantener estructurada la copia canónica.

Marcad también la página. Las entradas son obras con fecha y titular, y schema.org ofrece el vocabulario. Vale la pena por la misma razón que los permalinks: hace la página utilizable por cosas que no son un navegador, incluido el propio proceso de release de un cliente. Nada de esto funciona si las entradas subyacentes nunca fueron datos estructurados desde el principio; formatos de archivo de changelog cubre qué cuesta cada uno de Markdown, JSON y YAML como la fuente de verdad de la que realmente se generan este feed y este marcado.

¿Ayuda una página de changelog al SEO?

Indirectamente y despacio. Las entradas individuales rara vez posicionan, porque no apuntan a ninguna búsqueda que nadie teclea. La página se gana su lugar a través de enlaces: las entradas se citan en respuestas de soporte, foros y análisis de incidentes, y esos enlaces se acumulan en una URL que os pertenece. Una página actualizada semanalmente durante dos años es también una señal de frescura creíble para el producto al que pertenece.

Lo que no funciona es tratar las entradas como marketing de contenidos. Una entrada rellenada hasta tres párrafos para alargarla es peor en su trabajo real, que es decirle a un lector en una frase si algo que usa cambió. Si queréis que el changelog apoye la búsqueda, poned el esfuerzo en los permalinks, el feed y los enlaces internos hacia él, y dejad las entradas cortas. Nuestra propia página de ejemplos de changelog recopila páginas que aciertan este equilibrio.

¿Cómo se suscribe la gente?

Dadles las vías que ya usan: un feed RSS o JSON para desarrolladores, correo para quien solo quiere oír lo importante, y el widget en la app para todos los que nunca harán ninguna de las dos cosas. Preguntad qué quieren oír en lugar de asumirlo, porque un lector que quiere breaking changes y recibe ajustes de texto se da de baja de ambos.

La vía que conviene añadir al final es la que cierra el ciclo. Cuando una entrada resuelve algo que alguien concreto pidió, decídselo directamente en lugar de esperar que lea la página. En changeloop la entrada se publica en la página, el feed y el widget a la vez, y a una persona cuyo feedback en el widget se convirtió en el issue de GitHub que cerró el pull request se le avisa en ese issue con enlace a la entrada, y ve la entrada en el widget. La mecánica es la misma que cualquier suscripción; la diferencia es que quien la recibe ya preguntó. Es el argumento que se desarrolla en cerrar el ciclo de feedback desde el changelog.

FAQ

¿La página de changelog debería estar en un subdominio o en una ruta? Una ruta en el sitio principal por defecto, porque hereda la autoridad del sitio y no necesita infraestructura extra. Un subdominio se justifica cuando un sistema distinto sirve la página.

¿Cuántas entradas debería mostrar la página a la vez? Suficientes para llenar una pantalla y no más, con paginación después. Cargar dos años de historial en un documento es lento y hace más difícil encontrar la entrada más reciente.

¿Deberían borrarse alguna vez las entradas antiguas? No. Se citan desde fuera de vuestro sitio y los enlaces se rompen. Corregid una entrada en su sitio con una nota, y mantened viva la URL.

¿Tiene que aparecer en la página cada cambio? Solo los que un usuario podría notar. Una página que registra refactors internos entrena a los lectores a pasar por encima, y una página pasada por encima falla el día que lleva algo urgente.

Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.

Relacionado en changeloop: Ejemplos de changelog, Documentación para desarrolladores