La documentación técnica en vídeo sirve para explicar por qué un sistema está construido de una determinada manera. Funciona peor para describir pasos exactos que cambian con frecuencia. Esa diferencia decide si el esfuerzo se convierte en una referencia útil o en material desactualizado que nadie se atreve a retirar.
La charla de arquitectura que se repite cada vez que se incorpora una persona reúne las condiciones adecuadas: es estable, narrativa y costosa de repetir en directo. En cambio, una instrucción que depende de una versión concreta de una dependencia necesita una fuente que se pueda editar y revisar con rapidez.
Qué entra en la documentación técnica en vídeo y qué se queda en el repositorio
Un reparto práctico suele ser el siguiente:
| Tipo de documentación | Dónde vive | Motivo |
|---|---|---|
| Decisiones de arquitectura y su contexto histórico | Vídeo | Es narrativa, cambia poco y suele ser difícil de explicar solo con texto. |
| Recorrido general del repositorio | Vídeo | Ver a alguien navegar por los directorios resuelve dudas de orientación. |
| Configuración del entorno local | Markdown en el repositorio | Cambia con las versiones de las dependencias y debe poder corregirse en un pull request. |
| Runbooks de incidentes | Markdown, siempre | Durante una guardia se necesita buscar, copiar y ejecutar pasos con rapidez. |
| Referencia de API | Generada desde el código | El vídeo sería una copia menos precisa y quedaría desactualizado antes. |
La regla es sencilla: si la respuesta correcta puede quedar obsoleta sin que nadie lo note, no conviene grabarla. Un párrafo equivocado en el README se corrige en un pull request. Un minuto equivocado en un vídeo puede permanecer durante meses porque volver a grabar requiere coordinar tiempo y personas.
Los runbooks merecen una mención aparte. La idea de que un vídeo corto es más rápido que leer no se sostiene durante una guardia: cuando salta una alerta, se busca con Ctrl+F, se copia un comando y se pega en la terminal. Esas acciones no se pueden ejecutar sobre un vídeo.
Dónde colocar el guion en el proceso
La forma intuitiva de grabar es abrir el software de captura y empezar a hablar. El problema aparece al corregir: una frase mal planteada obliga a repetir la toma, encontrar un momento de silencio y volver a montar el material. Con ese coste, los errores pequeños suelen quedarse.
La alternativa es invertir el orden y empezar por el texto. Se escribe el guion como un documento normal, lo revisa una persona que conozca esa parte del sistema y solo después se convierte en vídeo. Para las partes narradas puede usarse una herramienta como Leadde.ai, que genera el vídeo a partir del guion y de las diapositivas. Corregir una frase consiste entonces en editar el texto y volver a generar el material.
El efecto más valioso no es solo el ahorro de tiempo: cuando corregir resulta barato, las correcciones se hacen. Además, revisar el guion antes de producir el vídeo permite detectar errores de contenido cuando todavía son fáciles de solucionar.
El coste de mantenimiento que aparece después de publicar
La mayoría de las guías sobre documentación en vídeo terminan cuando se publica el archivo. El trabajo real empieza después, cuando el sistema y el equipo siguen cambiando.
Hay tres situaciones que conviene prever antes de grabar:
Cambios de nombre. Renombrar un servicio, un repositorio o un proceso invalida cualquier vídeo que lo mencione. A diferencia del código, el vídeo no ofrece una búsqueda y reemplazo fiable.
Cambios de proceso. Si un despliegue pasa a hacerse de otra manera, queda obsoleto el tramo del vídeo que lo explicaba aunque el resto siga siendo válido.
Rotación de personas. Cuando se graba a personas reales, el material de incorporación puede caducar cuando esa persona deja la empresa. También puede resultar incómodo seguir mostrando a alguien que el equipo nuevo nunca conoció.
Una medida sencilla para los dos primeros casos es añadir una casilla a la plantilla de pull request: “¿Este cambio invalida algún vídeo?”. Se omitirá algunas veces, pero incluso una revisión ocasional ayuda a descubrir material que necesita una nueva versión.
Cuánto debe durar cada vídeo
Trasladar una charla presencial a vídeo sin cortarla es un error frecuente. La atención en una sala y la atención frente a una pantalla no se comportan igual, y una pieza larga puede abandonarse a mitad sin que nadie lo comunique.
El corte natural suele aparecer donde el ponente haría una pausa para beber agua. Si al escribir el guion aparece una frase como “ahora vamos a ver otra cosa distinta”, ahí puede terminar un vídeo y comenzar el siguiente.
Dividir por dominios del sistema suele funcionar mejor que dividir por duración. Un recorrido del repositorio puede ser más largo porque las personas saltan entre secciones. Una explicación de arquitectura conviene separarla en piezas que se puedan ver y comentar por separado.
Cómo preparar versiones en otro idioma
En equipos repartidos entre varios países, la documentación interna suele quedarse en el idioma de quien la escribió aunque las reuniones se celebren en otro idioma. Generar una versión traducida a partir del mismo guion es manejable cuando el guion existe como texto y resulta mucho más difícil cuando todo el material está encerrado en una grabación.
Conviene comprobar el uso real antes de traducir todo el catálogo. Es habitual que las personas técnicas lean el idioma original mejor de lo que el equipo supone y que la traducción se utilice menos de lo previsto.
Por dónde empezar
Empieza por la explicación que alguien del equipo está cansado de repetir. Esa pieza suele rentabilizar el esfuerzo porque evita la misma conversación cada vez que se incorpora una persona nueva.
Escribe el guion primero, aunque parezca posible improvisar. Antes de grabar, comprueba que el contenido no vaya a cambiar en el próximo ciclo de trabajo. Si va a cambiar, el repositorio es el lugar correcto; si explica una decisión estable y difícil de transmitir, el vídeo puede convertirse en una buena capa de contexto.
Top comments (0)