Vídeos de documentación de API que los desarrolladores sí ven

Una referencia de API escrita es precisa, completa y casi imposible como punto de partida. Quien llega a tu lista de endpoints entiende qué significa cada campo y aun así no tiene ni idea de cómo son los primeros cinco minutos usando la API.

Ese hueco es el que llena un vídeo corto. No sustituye a la referencia: la acompaña. Tres minutos mostrando una clave real, una petición real y una respuesta real responden a la pregunta que la documentación no puede contestar: ¿funciona como creo que funciona?

Así se graban esos vídeos para que sigan siendo útiles.

Decide qué merece un vídeo

El vídeo es caro de mantener. Gástalo donde el texto es más débil:

• La primera llamada con éxito: de un terminal vacío a una respuesta 200. Es el vídeo más valioso que puedes hacer
• Flujos de autenticación: las redirecciones de OAuth, el intercambio de tokens y el refresco son secuencias. Y para las secuencias está el vídeo
• Flujos de varios pasos: crear un recurso, consultar su estado, recuperar el resultado. La referencia los muestra como tres endpoints sin relación
• Webhooks y callbacks: dos sistemas hablando entre sí es realmente difícil de describir por escrito
• Errores habituales: un vídeo con un 401 y su solución evita más tickets que cualquier párrafo al respecto

Lo que no merece vídeo: los parámetros de cada endpoint, los valores de un enum, los límites de uso. Eso va en texto, donde se busca, se copia y se actualiza en segundos.

Prepara un sandbox de grabación

Nunca grabes contra producción con una clave real. Monta un entorno dedicado antes de pulsar Grabar.

• Una cuenta sandbox desechable, con claves que rotarás justo después
• Datos realistas: test_user_1 y "foo" hacen que la demo parezca falsa. Nombres, importes y marcas de tiempo verosímiles generan confianza
• Un formato de clave de vida corta, si tu API lo ofrece, para que un token visible un instante sea inofensivo
• Revisa el entorno del shell: la salida de env y el historial han filtrado más credenciales que ningún fragmento de código
• Precalienta cachés y dependencias para no grabar una instalación
• Desactiva las notificaciones: una vista previa de Slack en un vídeo publicado es un incidente real

Incluso en sandbox, trata cada fotograma como público. Alguien va a pausar.

Elige la configuración de captura adecuada

Una demo de API suele implicar dos o tres superficies: un terminal, un editor, un cliente de API como Postman o Insomnia y, a veces, un navegador para el panel.

• Captura de ventana por superficie: mantiene el encuadre ajustado y oculta el escritorio
• Si tienes que cambiar de aplicación, colócalas lado a lado de antemano y captura un área que abarque ambas. Alternar ventanas en cámara desorienta
• 30 fps bastan para contenido de texto, y una tasa menor deja más bitrate para caracteres nítidos
• Graba a resolución nativa: ampliar después es justo lo que produce el desenfoque
• Sube las fuentes a 18–24 pt en terminal y editor. Lo que parece exagerado en tu monitor es lo correcto en vídeo

Estructura todos los clips igual

La coherencia es lo que convierte un montón de capturas en documentación. Una estructura de cuatro tiempos que funciona:

1. Enuncia el objetivo en una frase: «Vamos a crear un cliente y cobrarle.»
2. Muestra la autenticación: aunque sea una sola cabecera. Hay que ver dónde va la clave
3. Construye la petición en directo: escríbela o pégala y repasa cada campo. Explica por qué está cada parámetro
4. Lee la respuesta en voz alta: haz una pausa sobre el JSON y señala el campo que importa para el siguiente paso

Cierra nombrando lo siguiente: «Ese id es el que usaremos para el cobro, y ese es el próximo vídeo.»

Haz legibles el JSON y el código

Aquí es donde fracasan la mayoría de los vídeos de API. La petición funciona, la respuesta llena la pantalla y el espectador ve un muro ilegible de llaves.

• Formatea siempre la salida: pásala por jq o activa el formateo del cliente
• Pliega lo irrelevante: casi todos los clientes permiten plegar secciones. Pliega los metadatos que no le importan a nadie
• Haz zoom sobre el campo clave: un zoom sobre las dos líneas que cuentan vale más que cualquier explicación. En Recorded puedes añadirlo después en el editor, así durante la grabación solo te ocupas de que las llamadas salgan bien
• Añade un texto con el nombre del campo: una etiqueta señalando subscription_status se lee antes de lo que tardas en decirlo
• Recorta la espera: latencia de red, bucles de sondeo y recompilaciones son tiempo muerto. Córtalos y deja que un rótulo breve indique cuánto pasó

Narra como un colega, no como una especificación

La descripción formal ya está en la referencia. Tu voz en off debe decir lo que la documentación no puede:

• «Esta cabecera es la que todo el mundo olvida.»
• «Sí, ese campo es obligatorio aunque parezca opcional.»
• «Si aquí te sale un 422, casi siempre es el formato de fecha.»

Ese tipo de comentario es el verdadero producto de un vídeo de documentación. Anota tres o cuatro antes de grabar: es fácil olvidarlos cuando estás concentrado en teclear bien.

Clips cortos y modulares

Un recorrido completo de la API de veinte minutos muere en cuanto cambia un endpoint. Los clips de dos a cuatro minutos centrados en una sola tarea duran mucho más y se pueden incrustar justo al lado de la sección de referencia que explican.

Modular también significa regrabable. Cuando cambia la forma del payload, vuelves a grabar noventa segundos en lugar de operar un vídeo largo.

Da por hecho que la API cambiará

El vídeo de documentación caduca antes que el texto. Tenlo en cuenta desde el principio:

• Di el número de versión en voz alta y muéstralo en pantalla, para que un vídeo obsoleto lo parezca
• Evita los adornos de interfaz que envejecen: un rediseño del panel avejenta el vídeo más rápido que cualquier cambio de API
• Guarda las grabaciones originales y los proyectos, no solo los exports, para que reeditar no signifique volver a rodar
• Nombra los archivos por endpoint y versión y sabrás qué actualizar tras cada release
• Revisa los clips en cada versión mayor y regraba los que ya mienten

Un vídeo breve y honesto del trimestre pasado no pasa nada. Un vídeo que enseña con seguridad un endpoint que ya no existe te cuesta credibilidad.

Publica donde surge la pregunta

El vídeo de API mejor colocado es el que está incrustado en la página de referencia de ese endpoint, no el archivado en una videoteca que nadie visita. Si pasa de dos minutos, añade capítulos o marcas de tiempo; pon bajo el reproductor el código completo del vídeo como texto copiable; y exporta un GIF corto de la respuesta correcta para la página de inicio rápido.

Lista rápida

• Cuenta sandbox con claves desechables
• Datos de prueba realistas
• Notificaciones apagadas, historial del shell limpio
• Fuentes ampliadas, ventanas colocadas
• Estructura objetivo → auth → petición → respuesta
• JSON formateado, zoom en los campos clave
• Tiempos de espera recortados
• Versión indicada en pantalla
• Incrustado junto a la sección de referencia
• Código copiable publicado con el vídeo

La referencia le dice al desarrollador qué es posible. Una buena grabación le demuestra que funciona de verdad, y eso suele ser lo que lo lleva a su primera llamada con éxito.