Cómo mantener la documentación al día cuando lanzas cada semana

por Fraser Hardy

Un pull request fusionado con líneas de diff en rojo y verde, y una flecha que lleva a un artículo de ayuda en el que el paso correspondiente aparece resaltado para su revisión, con botones de aceptar y descartar

Un cliente escribe: «Tu guía dice que vaya a Ajustes y luego a Calendario. No existe ningún Calendario». Tiene razón. Lo moviste a Cuentas hace seis semanas. El PR se revisó, se probó y se publicó. El artículo de ayuda no cambió, porque el trabajo de nadie era cambiarlo.

Así es como se queda obsoleta casi toda la documentación. No por pereza, sino por un eslabón que falta entre «hemos cambiado el producto» y «estos artículos describen la parte que cambiamos».

Para mantener la documentación al día cuando lanzas cada semana, haz que la documentación forme parte del pull request: cada PR responde a «¿cambia esto lo que ve un cliente?», nombra los artículos de ayuda que afecta y entrega la edición de la documentación en el mismo PR o en uno vinculado. Después, automatiza las partes mecánicas (capturas, entradas del registro de cambios) y vigila los tickets de soporte y las búsquedas del centro de ayuda para detectar el desfase que se escape.

El resto de esta entrada explica cómo montarlo sin contratar a un redactor técnico.

Por qué la documentación se queda obsoleta

El desfase de la documentación tiene unas cuantas causas previsibles, y ninguna se arregla con «seamos más cuidadosos».

La documentación vive en otro sitio. El código está en GitHub. La documentación está en Intercom, Zendesk, Notion o un espacio de GitBook. Nada conecta un archivo de uno con una página del otro, así que un cambio en uno nunca provoca que se mire el otro.

Quien sabe no es quien escribe. El ingeniero que movió los ajustes del calendario sabe exactamente qué cambió. La persona que mantiene el centro de ayuda se entera por un cliente.

La documentación se arregla por lotes. «Haremos una pasada por la documentación a final de trimestre.» Mientras tanto, cada lanzamiento semanal va minando la precisión, y la gran reescritura tarda tanto que ya está en parte obsoleta cuando sale.

Nadie sabe qué artículos están afectados. Ni siquiera un equipo motivado puede revisar 80 artículos después de cada lanzamiento. Así que no revisan ninguno.

Gráfico ilustrativo del desfase de la documentación a lo largo del tiempo: una línea de reescritura trimestral que cae tras cada lanzamiento semanal y solo vuelve a subir con la reescritura, mientras que una línea de actualizaciones por PR se mantiene cerca de la exactitud todo el tiempo

El patrón es el mismo que en cualquier otro trabajo de mantenimiento. Las actualizaciones pequeñas y continuas ganan a las proezas periódicas.

Haz que la documentación forme parte de la definición de terminado

El cambio más eficaz: añade una sección de documentación a tu plantilla de pull request. GitHub la rellenará de antemano en cada PR si pones un archivo en .github/pull_request_template.md (guía de GitHub sobre plantillas de PR).

## Docs impact

- [ ] This changes something a customer can see or do
- Help articles affected: <!-- slugs or links, or "none" -->
- [ ] Screenshots need re-capturing
- [ ] Changelog entry drafted (or marked "internal only")

Una plantilla de pull request con una sección de impacto en la documentación: casillas para indicar si el cambio es visible para el usuario, qué artículos de ayuda toca, si hay que volver a capturar pantallas y si se ha redactado una entrada de registro de cambios

Durante unas dos semanas parece burocracia. Luego se convierte en el momento en que un ingeniero dice «ah, el artículo de incorporación menciona esta pantalla» cuando el contexto aún está fresco. Un arreglo de documentación de dos líneas escrito por quien hizo el cambio es mejor que uno perfecto escrito un mes después a base de suposiciones.

Dos reglas hacen que se mantenga:

  1. Los revisores marcan la casilla. Si un PR cambia claramente la interfaz y dice «sin impacto en la documentación», el revisor pregunta por qué. Igual que con una prueba que falta.
  2. La edición de la documentación puede ser provisional. Los ingenieros no necesitan escribir una prosa pulida. «Paso 6 ahora: abre Cuentas y luego Ajustes de disponibilidad» basta. Alguien puede pulir la redacción después. Primero, la exactitud.

Asocia los artículos de ayuda al código que describen

La lista de comprobación del PR depende de que la gente recuerde qué artículos existen. Ayúdales con un mapa sencillo de rutas de código a artículos:

# docs-map.yml
- paths: ["src/features/calendar/**", "src/pages/accounts/availability*"]
  articles: ["connect-your-calendar", "set-your-availability"]
- paths: ["src/features/billing/**"]
  articles: ["change-your-plan", "update-payment-method", "download-invoices"]
- paths: ["src/features/onboarding/**"]
  articles: ["get-started"]

Después, un pequeño paso de CI lee la lista de archivos modificados (git diff --name-only origin/main...HEAD), los compara con los patrones glob y publica un comentario en el PR: «Este PR toca código del calendario. Revisa: connect-your-calendar, set-your-availability». Son quizá 40 líneas de script, y convierte «piensa en la documentación» en una lista concreta en la que se puede hacer clic.

El mapa también se queda obsoleto, claro. Mantenlo junto al código y añade una línea cada vez que alguien escriba un artículo nuevo. Sigue siendo mucho más fácil de mantener que la propia documentación.

Si tu documentación vive en el mismo repositorio (documentación como código con algo como Docusaurus, Mintlify o la sincronización con Git de GitBook), puedes ir más lejos: una entrada de CODEOWNERS sobre la carpeta de documentación garantiza que alguien a quien le importa la documentación revise cada cambio.

Escribe documentación que se pudra más despacio

Algunas decisiones de redacción hacen mucho más fácil el mantenimiento de la documentación:

Más sobre la estructura en nuestra guía sobre cómo escribir artículos de centro de ayuda que la gente realmente use.

Automatiza las partes mecánicas

Una parte del mantenimiento de la documentación es criterio. Mucha es simplemente tarea rutinaria que un script hace mejor.

Capturas de pantalla. Rehacer imágenes a mano es lo primero que hay que automatizar. Un script de Playwright contra una cuenta de demostración con datos de ejemplo, ejecutado en CI, te da imágenes frescas y coherentes en cada fusión. Repasamos el script completo en cómo crear capturas de pantalla de producto automáticamente.

Entradas del registro de cambios. Tus PR fusionados ya describen lo que se publicó. Convertirlos en un registro de cambios de cara al cliente consiste sobre todo en reescribir la jerga de ingenieros en lenguaje sencillo y agrupar por Añadido, Cambiado y Corregido, la convención popularizada por Keep a Changelog. Consulta cómo escribir un registro de cambios que los clientes lean para ver plantillas.

Vídeos. Si tienes vídeos tutoriales, el mismo mapa de rutas de código te dice cuáles hay que volver a grabar. Grabar imagen y voz por separado hace que repetirlo sea rápido; este es el proceso para los vídeos tutoriales de producto.

Encuentra el desfase que ya tienes

Incluso con un buen proceso, algunos cambios se cuelan. Estas señales te dicen dónde:

No documentes lo que no se ha publicado

Una trampa para equipos que se mueven rápido: un PR se fusiona detrás de un flag de funcionalidad, alguien actualiza diligentemente la documentación y ahora el centro de ayuda describe una función que la mayoría de los clientes no puede ver. Los clientes se confunden y soporte recibe los tickets.

Retén los cambios de documentación del trabajo protegido por flags hasta que el flag esté activo para todo el mundo (o escríbelos como borradores y publícalos con el despliegue). Lo mismo vale para las entradas del registro de cambios.

Herramientas que ayudan con el mantenimiento de la documentación

Los helpdesks como Intercom, Zendesk y Help Scout tienen editores de centro de ayuda perfectamente buenos, pero no tienen ni idea de lo que hay en tu código, así que todo el enlazado anterior corre de tu cuenta. Las plataformas de documentación como código, como GitBook y Mintlify, guardan la documentación en Git, lo que te da revisión de PR e historial, y funcionan mejor cuando quienes escriben se sienten cómodos en un repositorio. Las herramientas de centro de ayuda más nuevas, con la IA por delante, entre ellas Ferndesk, intentan cerrar la brecha desde otros ángulos.

Hemos construido Ellie Docs específicamente en torno al vínculo con el PR. Conectas un repositorio de GitHub y Ellie mapea tus funciones y vincula cada artículo de ayuda con las funciones que describe. En cada PR fusionado, comprueba qué artículos afecta el cambio y propone ediciones como un diff revisable, con una breve explicación de por qué. Aceptas o descartas cada una. Nada se publica por sí solo.

Una actualización sugerida por Ellie Docs a un artículo «Conecta tu calendario y previsualiza la disponibilidad» tras un PR fusionado, con el paso obsoleto tachado en rojo, los pasos nuevos en verde y los botones Aceptar y Descartar

También redacta entradas de registro de cambios a partir de los mismos PR fusionados y retiene todo lo que siga detrás de un flag hasta que se publique.

La página de registro de cambios de Ellie Docs con entradas redactadas a partir del código enviado, entre ellas un nuevo panel de ajustes de disponibilidad, cada una enlazada al artículo de ayuda relacionado y lista para publicar

Puedes hacer todo lo de esta entrada a mano, y muchos equipos lo hacen. Ellie simplemente se encarga por ti, cada vez, de la parte de «¿qué artículos afecta este PR y qué debería cambiar?».

Preguntas habituales

¿Quién debería ser responsable de la documentación en un equipo pequeño? Una persona concreta es responsable del centro de ayuda en su conjunto (a menudo el fundador o quien lleva el soporte), pero cada ingeniero es responsable del impacto en la documentación de sus propios PR. La responsabilidad compartida sin un responsable con nombre significa que no hay responsable.

¿Con qué frecuencia debemos revisar nuestra documentación? De forma continua para los cambios (mediante la lista de comprobación del PR), más un repaso mensual de tus artículos más vistos. Las grandes reescrituras trimestrales son señal de que la parte continua no está ocurriendo.

¿Merece la pena la documentación como código para la ayuda de cara al cliente? Si quienes escriben son ingenieros, sí. Si la mayor parte la escribe soporte o marketing, un editor de centro de ayuda normal más la lista de comprobación del PR y un mapa de documentación suele funcionar mejor que obligar a todo el mundo a usar Git.

¿Cuál es la victoria más rápida si nuestra documentación ya está muy desactualizada? Arregla los 10 artículos con más tráfico, añade la plantilla de PR y empieza a etiquetar los tickets de soporte que mencionen la documentación. Eso frena la sangría antes de abordar la larga cola.

Si prefieres que te propongan las actualizaciones de la documentación en cada PR, prueba Ellie Docs gratis. Conecta un repositorio, obtén un centro de ayuda redactado y revisa las ediciones sugeridas a medida que lanzas.