Animación del Mecanismo (mechanism-animation)
Convierte "cómo funciona" en una animación paso a paso en una página: el lector se desplaza un paso a la vez, cada paso cubre solo una cosa, y los elementos en la ilustración aparecen, se mueven y desaparecen en orden causal.
Referencia del producto terminado: assets/template.html, una plantilla con un pequeño ejemplo de 4 pasos (sin caché → añadir una capa de caché), que se puede abrir directamente en un navegador.
0. Primero, decidir si se debe hacer la animación
Prueba desde lo más barato a lo más caro; si el nivel anterior explica bien, no pases al siguiente:
| Nivel | Qué usar | Cuándo es suficiente |
|---|---|---|
| 1 | Escribir directamente | Se explica en dos o tres frases |
| 2 | Pasos numerados (1. 2. 3.) | Es un proceso, pero cada paso es una frase, el lector no necesita "verlo" |
| 3 | Pasos numerados + 2–3 imágenes fijas (antes/después) | Estructura, relaciones; o un proceso que se entiende con dos o tres imágenes fijas |
| 4 | Esta skill: animación paso a paso | Explica de dónde a dónde va algo, el orden secuencial, quién comparte los mismos datos, qué paso omitió algo, y tres imágenes fijas aún no lo explican |
Una frase para decidir: Si congelas la imagen en cualquier fotograma y el lector aún lo entiende ⇒ la imagen estática es suficiente; si necesita ver el movimiento para entenderlo ⇒ haz la animación.
Dos límites:
- Costo. La animación es varias veces más cara que la imagen estática (verificar hechos, ordenar, ajustar tiempo, probar, iterar). Cuando nadie pide explícitamente animación, primero propón, explica por qué los tres niveles anteriores no son suficientes, y solo hazla después de que la otra persona esté de acuerdo; no empieces por defecto.
- La animación solo sirve para "entender por primera vez", no como material de consulta: no se puede escanear, ni buscar, ni pegar en documentos. Por lo tanto, la página debe tener una sección de "resumen completo del proceso" al final (la plantilla lo genera automáticamente: una línea por paso); conserva la versión de texto original del documento y añade un enlace a la página de animación, no la reemplaces.
1. Proceso
- Verificar los hechos. La animación hará que los errores se vean muy vívidos. Antes de dibujar, verifica el mecanismo contra el código/documento de diseño/artículo, y distingue entre "dice esto en el diseño", "el código hace esto ahora", y "otros (artículo, valores por defecto) hacen esto". Si no estás seguro, escribe "inferido, pendiente de verificación".
- Escribir el guion gráfico (sin código). Sigue
references/storyboard.mdpara hacer una tabla: una línea por paso, especifica qué cosa explica este paso, qué aparece/se mueve en la imagen en orden, qué queda al final, y la frase de la izquierda. No empieces a dibujar hasta que el guion pase las reglas de la siguiente sección. Si hay muchos pasos (> 6) o no estás seguro de la explicación, primero verifica con la persona que solicitó: envía solo esa tabla más una pregunta que él debe resolver, no un documento completo; si la otra persona está acostumbrada a ver el producto final, hazlo directamente. - Partir de la plantilla:
cp assets/template.html <directorio_del_producto>/<nombre>.html. Solo cambia tres cosas:<title>en HTML, página de inicio (#top),aria-labelde la imagen, página de final (#where, incluye el pie de página "Actualizado: mes año · Verificado contra qué versión") — estas partes en la plantilla aún son contenido de ejemplo, cámbialas una por una;- Sección A del script:
PAGE,MODULES(módulos, pasos, texto, duración de cada paso); - Sección C del script: la escena (qué objetos hay, cómo se mueven en cada paso).
Las secciones B1/B2 son el motor, generalmente no se tocan. Para escritura, herramientas pequeñas y trucos existentes, consulta
references/engine.md.
- Autoprueba:
node scripts/check.js <página.html> <directorio_de_capturas>, 10 elementos sin FAIL (containes SKIP si la página no tiene marcador de pertenencia, es normal), luego revisa cada captura una por una:step-NN(final de cada paso),mid-NN(mitad de cada paso),page-NN(página completa). El script solo puede verificar "se detuvo o no, si se superpone texto, si se sale del marco, si el texto es lo suficientemente grande", no puede verificar "si explica bien o no". Una página de 4 pasos toma aproximadamente 1 minuto, 12 pasos aproximadamente 3 minutos; instala dependencias y consulta el uso al final de engine.md. 4.5 (Cuando hay muchos pasos o se explica a no expertos) Prueba de "persona que ve por primera vez": inicia un subagente que no conoce este mecanismo y no ha leído ningún material, solo dale las capturas de cada paso de la página, que las vea en orden, y luego que recite de memoria qué explicó cada paso, si lo entendió por la imagen o por el texto, y qué no entendió. Lo que no entienda es un problema de la página, no suyo — más efectivo que revisarlo diez veces uno mismo. - Entrega: entrega la página (un solo HTML, sin dependencias de otros archivos) a la persona que la solicitó. Después de cada modificación, vuelve a ejecutar la autoprueba antes de entregar.
- (Cuando el contenido es importante) Verificación técnica: una vez finalizada la página, inicia una ronda de verificación solo de lectura, verifica cada frase y cada número en la página contra el código y los documentos, y genera una lista de "incorrecto/engañoso/impreciso", que la persona que solicitó decidirá qué cambiar. La verificación solo se ocupa de los hechos; la calidad de la explicación la evalúa la persona que solicitó.
2. Reglas de explicación (las más importantes, se aprenden después de que te rechacen)
Orden
- Primero lo fácil, luego lo difícil; primero la situación "sin problemas", luego la "con problemas". El lector primero ve cómo es normal, luego puede ver el problema. Ejemplo: primero explica que muchas máquinas virtuales comparten memoria (sin problemas), luego que al cambiar a muchas máquinas virtuales cada una guarda su propia copia (problema), luego la solución.
- Primero la capa inferior, luego la superior, apareciendo capa por capa. Primero solo el host → los datos entran del disco a la memoria del host → aparece la máquina virtual → los datos entran a la máquina virtual → finalmente aparece el programa dentro. No coloques todos los cuadros desde el principio, ni dejes que el programa aparezca antes que los datos.
- Si varias cosas en un paso tienen una relación causal, ordénalas, no ocurran al mismo tiempo. Después de que "el contenedor sale", "su memoria se libera", y luego "se devuelve al host".
- La imagen aparece después de que el desplazamiento se detenga; la animación del primer paso se reproduce desde el principio; la plantilla ya maneja esto, no lo estropees.
Qué explicar en cada paso
- Un paso solo cubre una cosa, el título es esa cosa ("Cada página lee una vez"), no un sustantivo ("Fase de lectura").
- La línea principal solo muestra la práctica real. Los valores por defecto, las prácticas de otros, las soluciones históricas, se mencionan en los puntos clave de este paso con una frase "por qué se hace así", no los conviertas en un paso separado — de lo contrario, el lector pensará que la práctica real también requiere ese paso primero. (Contraejemplo: primero muestra "reportar en 2 MB" y luego "reportar en 4 KB", el lector pregunta "¿De dónde salen los 2 MB? ¿Cuál va primero?").
- Dos pasos que se ven iguales, el lector pensará que son la misma cosa. Si dos escenarios tienen diferencias, dibuja las diferencias (varias flechas convergiendo en los mismos datos, un círculo marcando la copia compartida), no solo lo digas en el texto.
- Cada número y cada palabra en la imagen debe tener un origen. Los números que no se han explicado antes ("18", "2 MB") confundirán al lector; o explícalos, o elimínalos.
- Cuando un problema solo pertenece a un cierto tipo de solución, colócalo en el módulo de esa solución, no en la parte general para que el lector piense que todos tienen ese problema.
- Usa ejemplos concretos que el lector reconozca, no símbolos abstractos. Varias líneas, puntos o barras pequeñas moviéndose, el lector no sabe qué son (cita del lector: "Esas 4 barras de progreso... No sé qué significan"). Conviértelos en algo que se pueda nombrar: quién, a quién, dijo qué (el Agente del "sistema de pago" pregunta al Agente de la "plataforma de datos" "¿Cómo se llama la interfaz de pedidos?", el otro responde "El documento de la interfaz ya se ha enviado"); usa solo símbolos que el lector ya haya visto antes (esas líneas en la lista anterior), no inventes nuevos. Un ejemplo bien explicado es mejor que tres pares abstractos de intercambios; si el ejemplo es bueno, añade otro diferente, no repitas el mismo ejemplo tres veces.
- No dibujes capas y objetos que no se usen en este paso. "Aparecer capa por capa" no significa que cada capa deba aparecer: al explicar "el contenedor devuelve la memoria a la máquina virtual", dibujar el host hace que el lector tenga que reconocer una capa más sin aprender nada nuevo (cita del lector: "No es necesario mostrar el host, es un poco complicado"). Antes de dibujar, pregúntate: sin él, ¿la frase de este paso aún se sostiene? Si se sostiene, elimínalo.
- Al terminar, responde "¿Y qué?". El último paso de cada módulo o la página final deben dejar claro: ¿qué significa esto para el lector? ¿En qué punto está ahora (ya en producción / solo en entorno de prueba / aún no hecho)?
- La profundidad se define según el lector. Antes de dibujar, escribe "quién es el lector, qué sabe ya, qué no le importa": explicar conceptos básicos a expertos se considerará demasiado detallado, y dar detalles de implementación a no expertos se considerará demasiado específico.
Texto
- Cada paso: una frase (lead) + máximo 2–3 puntos clave, negrita solo para números o palabras concluyentes. Si el texto de la izquierda es demasiado largo, elimina detalles; los detalles van en la página final o en una nota pequeña en la esquina inferior derecha de la imagen.
- No hagas referencia a cosas que se explicarán más tarde. Frases como "ya no se guarda una copia cada uno", "todavía", "igual", "esa copia" deben referirse a cosas que ya han aparecido antes. Después de reorganizar el orden de los capítulos, lee el texto movido de nuevo desde el principio en el nuevo orden.
- El primer término que aparezca se explica en media frase en ese momento, y se usa el mismo nombre para la misma cosa en toda la página.
- No aparecen nombres internos en la página: números de RFC, números de PR, nombres de archivos, nombres de funciones, nombres de comandos, nombres de máquinas internas. Esto es una excepción cuando el lector es el desarrollador de este código.
- Los términos y "número + unidad" no se separan en líneas: envuélvelos en
{{ }}, como{{4 KB}},{{1,380 millones de tokens}}. - Pie de página: "Actualizado: mes año · Verificado contra la versión X del código". La página es una instantánea de ese día; el código cambia.
- Lo que es inferido y no verificado, escríbelo como "inferido", "pendiente de verificación"; los números de otros, especifica de quién son ("artículo", "POC", "en main").
Imagen
- La misma cosa es el mismo objeto durante todo el proceso: un bloque de datos "vuela" del disco a la memoria, luego "vuela" a la máquina virtual, no desaparece aquí y aparece allá. El lector se basa en esto para seguir el proceso.
- Los colores tienen un significado fijo, coherente en toda la página (por ejemplo: cian = datos, púrpura = programa, naranja = acción en curso, azul = conclusión / devuelto). La leyenda solo muestra los colores usados.
- Las acciones también tienen un significado fijo, no cambies el uso en toda la página (por ejemplo: línea naranja dibujada = enviar solicitud, bloque de color que vuela = datos entregados, círculo naranja = la copia compartida, grupo entero atenuado = ya no se usa). La misma acción debe tener la misma velocidad: los que viajan más lejos tardan más, no los comprimas en la misma duración.
- El estado se muestra con color, y solo con dos o tres tipos: por ejemplo, "azul = en uso, gris = liberado". El lector puede contar de un vistazo cuántos azules y cuántos grises hay, y luego entender "los grises son retirados"; no uses color, icono y texto para decir lo mismo.
- El texto que se lee no se mueve: si una frase debe transmitirse de A a B, deja la frase quieta al lado de quien habla, y envía un pequeño marcador a lo largo de la línea; el lector lee las palabras quietas, ve el camino del marcador. Si las palabras vuelan, el lector no ve ni lo uno ni lo otro.
- Primero mover, luego detenerse: la acción principal del paso se completa dentro del 60% del tiempo, luego la imagen se queda quieta, dejando al lector leer la frase de la izquierda; dos acciones importantes no ocurren al mismo tiempo; los movimientos grandes no duran menos de medio segundo, los que cruzan toda la imagen no menos de 0.7 segundos; más rápido y el ojo no lo sigue.
- Cómo entra, cómo sale: los cuadros dibujados con líneas, al salir se retiran con líneas; lo que vuela, vuela hacia afuera. Usa solo dos o tres técnicas para entradas y salidas en toda la página; no hagas de la disolución la técnica por defecto.
- Cuando varias líneas convergen en el mismo objetivo, entra desde diferentes direcciones (una desde la izquierda, una desde arriba, una desde la derecha), no las coloques paralelas en el mismo borde: tarde o temprano se superpondrán, o pasarán detrás de otras figuras (cita del lector: "la línea del teléfono y la del cliente se superpusieron, y el teléfono bloqueó la línea del cliente").
- Si el significado es correcto pero no es bonito, tampoco está terminado (cita del lector sobre una nube: "El significado es correcto, pero la nube es demasiado fea y tosca"). Las figuras clave (las que aparecen repetidamente en toda la página, aquellas en las que cae el último paso) primero dibuja dos o tres versiones una al lado de la otra, elige una; al elegir, pregúntate: ¿las líneas tienen la misma sensación que las otras cosas en la página? ¿La proporción es cómoda? ¿Se distingue de las líneas detrás?
- Las marcas de énfasis (círculos, flechas, texto naranja pequeño) aparecen solo cuando se explican y desaparecen al terminar, a más tardar al inicio del siguiente paso, no las lleves a pasos posteriores. La imagen al final de cada paso debe tener sentido por sí sola (
step-NN.pnges esa imagen). - Para enfatizar compartir / la misma copia: varias flechas convergen en una sola que cae en el mismo objetivo, y añade un círculo naranja.
- "Se omitió" y "se devolvió" deben mostrarse: las cosas vuelan al segmento correspondiente en la barra de uso, y después de aterrizar, ese segmento se acorta; no lo acortes mientras vuela. La posición a la que vuela debe coincidir con el segmento que se acorta.
- Cuando la representación no coincide con el tamaño real, marca "esquemático" y no dejes que el tamaño de la cuadrícula esquemática sugiera una unidad que no existe.
- El anidamiento de cuadros y los nombres deben corresponder a la propiedad real: antes de dibujar, haz una lista "objeto → en qué espacio de red/contenedor/proceso/servicio está realmente". Los contenedores o procesos independientes (sidecar, proxy) se dibujan como cuadros paralelos, no dentro del contenedor de negocio; el cuadro externo debe indicar claramente qué es ("espacio de red de un grupo de contenedores"), y el nombre del cuadro debe ser el que el lector usa mentalmente ("contenedor de negocio", no "contenedor principal"); cuando hay cosas con el mismo nombre, distingue la propiedad (cuando dos servicios tienen un componente llamado sidecar, usa el nombre completo fijo para cada uno), no mezcles en la imagen ni en la columna izquierda.
- Mientras menos esquinas tengan las líneas, mejor: los extremos caen en los bordes opuestos de dos cuadros, no apuntes al centro del cuadro; si la altura de dos cuadros se superpone, una línea recta; si hay que doblar, solo un punto de giro definido (máximo dos para forma de U para evitar obstáculos), asegúrate de que el punto de giro evite el texto; los paquetes de datos, líneas rojas, etc., que siguen el mismo camino comparten estos puntos de giro. Las pequeñas curvas harán que el lector piense "esto tiene un significado especial".
check.jsdetectará las curvas excesivas. - Las pequeñas notas explicativas se colocan al lado del cuadro, no sobre los objetos dentro del cuadro.
- El texto en la imagen no debe ser menor de 14 unidades de lienzo. La imagen se reduce a aproximadamente 0.8x en una laptop de 13 pulgadas; más pequeño y no se ve claro;
check.jsverifica que el tamaño de fuente sea al menos 11px en 1280×720. Si no cabe, elimina contenido, no reduzcas el texto. La plantilla tiene una opción de "imagen ampliada" (botón en la parte superior / tecla F), que es una opción para el lector, no una solución para texto pequeño.
3. Retrabajos comunes (cuando recibas esta retroalimentación, corrige directamente así)
| Retroalimentación | Causa probable | Cómo corregir |
|---|---|---|
| "La animación de este paso no termina / hay un problema al final" | Los fotogramas clave están programados después del final de este paso, o la disolución coincide justo con el momento de finalización | Todas las acciones de este paso deben comenzar antes de T(id, 0.88) y detenerse antes de T(id, 1); check.js lo detectará en el elemento still |
| "El texto se sale del marco / la posición es incorrecta" | El cuadro padre y el contenido interior no comienzan a moverse al mismo tiempo; se escribió un fotograma adicional que solo cambia el color y fija la posición | Usa el mismo conjunto de tiempos para padre e hijo; márcalos con data-box / data-in, y verifica fotograma a fotograma con el elemento contain. No uses otros indicadores (tamaño de fuente, transparencia) como sustituto de "dentro del marco" |
| "El paso N y el paso M se ven iguales" | Las diferencias solo están escritas en el texto | Dibuja las diferencias (ver arriba: flechas convergentes + círculo) |
| "¿De dónde salió X?" | Hay un número/unidad no explicado en la imagen | Explica el origen, o elimínalo de la imagen, y solo menciónalo en un "por qué" |
| "El orden está mal, debería ser A antes que B" | No se ordenó por causalidad / por capas | Reordena los tiempos de este paso según "primero la capa inferior, luego la superior"; aprovecha para revisar también los otros pasos |
| "XX es extraño, no se mencionó antes" | El texto hace referencia a algo que se explicará después | Busca con grep "ya no, cada uno, todavía, igual, esa copia, comparar", y verifica cada caso para asegurarte de que lo referido ya ha aparecido |
| "Demasiado texto / no se ve claro / demasiado pequeño" | Detalles apilados en la columna izquierda; texto en la imagen menor de 14 | Reduce a una frase + puntos clave; ajusta el texto en la imagen a 14 o más; si no cabe, elimínalo; check.js lo detectará en los elementos fontsize y text |
| "Al bajar desde la página de inicio, la animación del primer paso no se reproduce / no se reproduce al recargar" | Se dañó la lógica de entrada en el motor | No toques la sección B2, ni enteredFirst, pendingShow, las primeras líneas; check.js lo detectará en el elemento wheel |
| "¿Por qué hay una curva así?" (con captura de pantalla) | La flecha apunta al centro del cuadro del otro, o los puntos de giro se calculan por separado, creando una pequeña ida y vuelta; los paquetes de datos y las líneas en el mismo camino van por rutas separadas | Coloca los extremos en los bordes opuestos; si es posible, recto; máximo un punto de giro; los paquetes de datos y las líneas comparten los puntos de giro; check.js lo detectará en el elemento bends. Revisa todas las líneas de la imagen una por una |
| "¿X es un Y independiente? ¿Está bien dibujado dentro de Z?" "Esta parte debería llamarse... ¿es más preciso?" | El anidamiento de cuadros no corresponde a la propiedad real (dibujaste el sidecar dentro del contenedor de negocio), o el nombre del cuadro usa un nombre interno | Primero haz la lista "objeto → propiedad real" y luego corrige el anidamiento; el cuadro externo debe indicar claramente qué es, y el nombre del cuadro debe cambiarse al nombre que usa el lector; revisa todos los cuadros similares en toda la página |
Cuando recibas una retroalimentación, piensa primero si esta retroalimentación también es válida en otros pasos y corrígelos todos juntos, no esperes a que la otra persona señale cada uno.
4. Archivos
| Archivo | Contenido |
|---|---|
assets/template.html | Plantilla (motor + ejemplo de 4 pasos) |
scripts/check.js | Script de autoprueba (10 elementos + capturas) |
references/storyboard.md | Cómo escribir un guion gráfico, un ejemplo real de un guion de 12 pasos |
references/engine.md | Estructura de la plantilla, herramientas pequeñas, patrones visuales, problemas comunes, cómo ejecutar la autoprueba |
references/lessons.md | Registro de retroalimentación de varios productos terminados (origen de las reglas); si encuentras una situación no cubierta por las reglas, busca aquí la más similar |