Cómo actualizar automáticamente la documentación en cada lanzamiento

Actualizado el 3 de noviembre de 2026

Para actualizar automáticamente la documentación en cada lanzamiento, inicia una tarea de documentación desde el lanzamiento mismo: un lanzamiento publicado en GitHub, un evento de lanzamiento en GitLab, una etiqueta en Bitbucket o una nueva entrada en tu registro de cambios público. La tarea lee las notas de la versión, encuentra las páginas de ayuda y los videos que el lanzamiento afecta, redacta los cambios y los envía a una persona para su aprobación. Para la documentación orientada al cliente, ese paso de revisión es lo que mantiene segura la automatización de la documentación.

Esta guía recorre ese proceso primero con cualquier herramienta (GitHub Actions, GitLab, Bitbucket, una página de registro de cambios) y luego muestra cómo el Autopilot de Clevera ejecuta el mismo ciclo para un centro de ayuda con videos.

¿Qué es la documentación continua?#

Swimm, que popularizó el término, define la documentación continua como la creación y actualización de documentación de forma incremental como parte del flujo de trabajo de desarrollo, en lugar de hacerlo en proyectos de puesta al día ocasionales. La mayoría de las herramientas creadas bajo esta idea, que ahora suelen venderse como "documentación autoactualizable", observan las confirmaciones (commits) o las solicitudes de extracción (pull requests) y actualizan la documentación para desarrolladores junto al código.

Los centros de ayuda orientados al cliente necesitan un activador diferente. Los lectores no ven una confirmación; ven un lanzamiento. La tabla muestra el compromiso.

El argumento a favor de la automatización es el ritmo. La investigación State of DevOps 2021 de DORA descubrió que los equipos de élite despliegan 973 veces más frecuentemente que los de bajo rendimiento. No todos los despliegues cambian lo que ven los lectores, pero los equipos envían actualizaciones mucho más a menudo de lo que alguien puede revisar los artículos manualmente. La misma investigación descubrió que los equipos con documentación de alta calidad tenían 3,8 veces más probabilidades de implementar las mejores prácticas de seguridad, por lo que la documentación no es un tema secundario. Y la documentación desactualizada es común: en la Encuesta de Código Abierto de 2017 de GitHub, el 93% de los encuestados se había encontrado con documentación incompleta o desactualizada, y el 60% de los colaboradores dijeron que rara vez o nunca contribuyen a la documentación.

Paso 1: Escribe notas de la versión que una tarea de documentación pueda usar#

La automatización solo puede actualizar la documentación tan bien como las notas de la versión describan el cambio. Dos convenciones ayudan.

• Agrupa los cambios por tipo. Keep a Changelog utiliza Added (Añadido), Changed (Cambiado), Deprecated (Obsoleto), Removed (Eliminado), Fixed (Corregido) y Security (Seguridad). "Added" suele significar un nuevo artículo o video; "Changed" y "Removed" significan que el contenido existente ahora es incorrecto.
• Separa lo que los usuarios ven de lo que no. Las notas de la versión generadas automáticamente de GitHub clasifican las solicitudes de extracción fusionadas por etiqueta en .github/release.yml, y pueden excluir etiquetas por completo.

# .github/release.yml
changelog:
  exclude:
    labels: [internal, chore]
  categories:
    - title: New
      labels: [feature]
    - title: Changed in the app
      labels: [ui-change]
    - title: Fixes
      labels: [bug]
    - title: Other changes
      labels: ["*"]

Una etiqueta "ui-change" es la etiqueta más útil para añadir: le dice a la tarea de documentación qué elementos pueden romper un artículo. Nombra la pantalla en el título de la solicitud de extracción también ("Billing settings: move reminders to Automations"), para que el cambio pueda coincidir con las páginas que muestran esa pantalla.

Paso 2: Actualiza automáticamente la documentación al lanzar: inicia una tarea#

Cada host de Git importante puede iniciar una tarea cuando realizas un envío, que es cómo generas actualizaciones de documentación desde lanzamientos de GitHub o sus equivalentes en GitLab y Bitbucket. Los detalles difieren.

En GitHub, un flujo de trabajo mínimo se ve así:

# .github/workflows/docs-on-release.yml
name: Docs on release
on:
  release:
    types: [published]
permissions:
  contents: read
jobs:
  draft-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - name: Draft docs updates for this release
        env:
          TAG: ${{ github.event.release.tag_name }}
          NOTES: ${{ github.event.release.body }}
        run: ./scripts/draft-docs-updates.sh

Usa published en lugar de created: según la referencia de eventos de GitHub, created no se dispara para lanzamientos en borrador, mientras que published cubre tanto lanzamientos estables como prelanzamientos. Pasa las notas de la versión a través de una variable de entorno como se indicó anteriormente, no directamente al comando de shell, porque el texto del lanzamiento es entrada del usuario. Y si una herramienta como release-please o semantic-release crea tus lanzamientos con el token predeterminado, los eventos que dispara no iniciarán tu flujo de trabajo de documentación; dale a esa herramienta un token de GitHub App o un token de acceso personal en su lugar.

En GitLab y Bitbucket, el equivalente es una tarea que se ejecuta en etiquetas:

# .gitlab-ci.yml
draft-docs:
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - ./scripts/draft-docs-updates.sh "$CI_COMMIT_TAG"

# bitbucket-pipelines.yml
pipelines:
  tags:
    'v*':
      - step:
          script:
            - ./scripts/draft-docs-updates.sh "$BITBUCKET_TAG"

Paso 3: Encuentra las páginas y videos que cada lanzamiento afecta#

Este es el paso que la mayoría de las guías omiten, y el que decide si la automatización ayuda. Una nota de la versión dice "Recordatorios movidos a Facturación → Automatizaciones"; tu tarea tiene que convertir eso en "estos tres artículos y dos videos ahora son incorrectos".

Tres métodos, del más simple al más fuerte:

1. Busca etiquetas renombradas. Extrae cada cadena de interfaz de usuario entre comillas de las notas de la versión y busca en tus artículos y guiones de video la redacción antigua.
2. Mantén un inventario de pantallas. Etiqueta cada artículo y video con las pantallas que muestra, y haz coincidir los nombres de las pantallas en los títulos de las solicitudes de extracción con él. Nuestra guía para mantener la documentación actualizada tiene una plantilla de inventario.
3. Deja que un modelo lea cada candidato completo. Dale a un modelo de lenguaje las notas de la versión y el texto completo (o transcripción) de cada página candidata, y pide un veredicto: sigue siendo correcto, necesita una corrección de texto, o necesita nuevas capturas de pantalla o metraje. Leer toda la página importa, porque el paso roto a menudo no es el que nombra la nota de la versión.

Un aviso para ese veredicto puede ser corto:

You check help articles against a software release.
Release notes: {release_notes}
Article ({url}): {article_text}

Answer in JSON: {"verdict": "still_right" | "text_fix" | "new_screenshots_or_footage",
"reason": "<one sentence quoting the release item>",
"changed_steps": [<step numbers>]}
Only use facts from the release notes. If unsure, answer "text_fix" and say why.

Paso 4: Redacta las actualizaciones#

Para el texto, el borrador es la parte fácil: el modelo obtiene las notas de la versión, el artículo actual y tus reglas de estilo, y devuelve una versión revisada. Mantén el ID y la URL del artículo, para que actualices la página existente en lugar de crear un duplicado casi idéntico, y registra qué lanzamiento lo cambió por última vez. Las reglas en cómo escribir artículos para el centro de ayuda hacen un buen aviso de estilo.

Las capturas de pantalla y los videos son más difíciles. Un modelo no puede producir una captura de pantalla de una pantalla que no ha visto. O capturas nuevas imágenes en tu conjunto de pruebas de interfaz de usuario, vuelves a grabar el flujo cambiado, o marcas el elemento para que una persona lo vuelva a grabar. Marca cada elemento en el plan: corrección de texto, nueva captura de pantalla o volver a grabar. Una vez que se graba el flujo cambiado, convertir la grabación en documentación te da nuevos pasos y capturas de pantalla en una sola pasada.

Paso 5: Pon a una persona entre el borrador y el lector#

Las descripciones de las solicitudes de extracción son escritas por muchas personas y nunca se revisan pensando en los clientes. Trátalas, y a las notas de la versión, como entradas no confiables: pueden llevar instrucciones que un modelo seguirá. Envía cada borrador a revisión.

• Quién aprueba: el responsable de soporte o documentación para el contenido del centro de ayuda, un ingeniero para la referencia de API.
• Qué muestra una buena revisión: cada página afectada con una comparación de antes y después, el elemento de lanzamiento que la causó, y una lista clara de "nada que cambiar" para que los revisores confíen en lo que se omitió.
• Qué publicar automáticamente: nada orientado al cliente al principio. Una vez que algunos lanzamientos hayan pasado sin sorpresas, puedes relajar la regla para elementos de bajo riesgo como correcciones de texto de nivel de error tipográfico.

¿Qué configuración se adapta a tu equipo?#

Si tu equipo ya trabaja en Claude Code, también puedes pedirle que actualice los docs después de un lanzamiento a través de MCP; explicamos cómo hacerlo en cómo actualizar docs con Claude Code después de cada lanzamiento.

Cómo actualizar automáticamente la documentación en el lanzamiento con Clevera Autopilot#

Clevera es una plataforma de IA que convierte una grabación de pantalla en un video instructivo narrado, un artículo de ayuda paso a paso y una página en tu centro de ayuda alojado, en 74 idiomas. Su función Autopilot, disponible en los planes Pro y Custom, ejecuta los pasos 2 al 5 anteriores para un centro de ayuda de Clevera.

• Disparador. La receta Mantener mi centro de ayuda actualizado cuando lanzamos observa los Lanzamientos o Cambios fusionados de un repositorio, o una Página de registro de cambios leída diaria o semanalmente. GitHub se conecta a través de una aplicación de solo lectura; GitLab (gitlab.com) y Bitbucket Cloud se conectan de la misma manera cuando está disponible. Clevera revisa el repositorio aproximadamente una vez por hora. Lee notas de lanzamiento, etiquetas y títulos y descripciones de pull-requests, nunca tu código.
• Coincidencia. Cada ejecución revisa hasta 40 de los videos y artículos del centro de ayuda y lee cada uno de los afectados por completo.
• Redacción. Cada elemento obtiene un veredicto: sigue siendo correcto, una corrección de texto mostrada antes y después, o grabar de nuevo con los nuevos pasos. La nueva grabación requiere Usar mi aplicación: la dirección de tu aplicación y, si lo necesita, un inicio de sesión (una cuenta de prueba funciona mejor). El nuevo video reemplaza al anterior en el mismo enlace, por lo que, al igual que con las ediciones de LiveSync, los incrustados y las páginas del centro de ayuda lo muestran sin necesidad de nuevos enlaces.
• Revisión. Cada ejecución espera por ti. Desmarcas lo que no quieres y haces clic en Ejecutar, o haces clic en Pedir cambios para obtener un nuevo plan. Un plan caduca después de siete días, y la siguiente ejecución recoge todo lo ocurrido desde entonces.

Observar y planificar es gratis; cada línea de un plan muestra sus créditos, y una ejecución típica cuesta de 10 a 150 créditos. El mismo bucle está disponible para videos sin un centro de ayuda a través de Actualizar mis videos cuando el producto cambia, y Grabar un video para cada nueva función propone un nuevo instructivo para lo que añade cada lanzamiento (consulta cómo hacer un video de notas de lanzamiento para la versión manual).

Donde Clevera no es la herramienta adecuada: no genera referencias de API a partir de código ni escribe tu CHANGELOG.md. Para ese aspecto, consulta nuestra comparación de generadores de registro de cambios con IA, o servidores MCP para documentación si deseas que un agente de IA edite docs en otra plataforma.

Comienza gratis para construir primero el centro de ayuda y los videos; Autopilot viene con Pro. Los pasos de configuración están en el artículo de ayuda Conectar GitHub u otro repositorio a Autopilot.

Preguntas frecuentes#

¿Puede la documentación actualizarse automáticamente cuando lanzamos?#

La detección y la redacción pueden ser automáticas: un lanzamiento inicia un trabajo que encuentra las páginas afectadas y redacta las correcciones. La publicación debe seguir siendo una decisión humana para los docs dirigidos al cliente, porque las notas de lanzamiento no siempre dicen lo que pretendías que hicieran los lectores.

¿Deberían actualizarse los docs en cada commit o en cada lanzamiento?#

Para centros de ayuda, en cada lanzamiento. Los commits y pull requests cambian constantemente y a menudo permanecen detrás de indicadores de funciones; un lanzamiento es cuando los lectores realmente ven el cambio. Los docs para desarrolladores que viven junto al código pueden seguir los pull requests.

¿Cómo disparo una GitHub Action cuando se publica un lanzamiento?#

Usa on: release con types: [published]. Si el lanzamiento es creado por otro flujo de trabajo usando el GITHUB_TOKEN predeterminado, no iniciará tu flujo de trabajo; usa un token de GitHub App o un token de acceso personal para la herramienta de lanzamiento.

¿Qué pasa si no publicamos lanzamientos en GitHub?#

Usa la señal que sí tengas: eventos de lanzamiento de GitLab, pipelines de etiquetas de Bitbucket o un trabajo programado que lea tu página pública de registro de cambios o su feed RSS. El Autopilot de Clevera puede observar una página de registro de cambios diaria o semanalmente para este caso exacto.

¿Pueden las capturas de pantalla y los videos actualizarse automáticamente también?#

Las capturas de pantalla pueden capturarse en pruebas de UI en cada compilación. Los videos necesitan que el flujo cambiado se grabe de nuevo; un grabador de IA puede volver a ejecutar una instrucción guardada contra la nueva UI, y Autopilot puede hacer esto para los videos de Clevera cuando le das la dirección de tu aplicación (y un inicio de sesión si tu aplicación lo necesita). Mira la nueva toma antes de aprobarla.