IbrahimSobh/content-explainer-slide

Diapositiva Explicativa de Contenido

Construye una imagen que cuenta la historia de un trabajo técnico: qué se notó, qué estaba mal, qué se hizo y por qué funciona cada paso, de dónde viene cada número, y qué se logró y aprendió.

El estándar es 100% claro e intuitivo para un ingeniero junior, no 100% detallado. Ese estándar proviene de rondas de revisión reales: cada vez que un término no estaba definido, un número no tenía un origen visible, la razón de un paso estaba oculta en una nota al pie, o una tarjeta tenía un área vacía, el lector regresaba con "¿qué es esto?", "¿de dónde salió 30?", "¿por qué funciona eso?" — y la diapositiva necesitaba otra ronda. Todo lo que sigue existe para responder esas preguntas en la diapositiva antes de que el lector tenga que preguntar.

Un ejemplo trabajado de un plan de diapositiva terminado (un experimento de "cirugía de neuronas" de una red neuronal) está en references/worked-example.md. Léelo una vez antes de planificar tu primera diapositiva; muestra cómo se ve cada tarjeta cuando se aplican las reglas.

Paso 0 — Preguntar el formato de salida, luego construir una hoja de hechos

Preguntar el formato (una vez, antes de dibujar)

Preguntar al usuario qué formato de salida quiere, a menos que ya lo haya dicho:

• PNG via matplotlib (Python) — mejor cuando la entrada tiene datos, modelos, logs o archivos de resultados, porque un script puede calcular cada número de la diapositiva directamente desde esos archivos (sin números escritos a mano). También exporta una copia JPG.
• HTML/SVG renderizado a PNG — mejor cuando la entrada es solo texto (un artículo, un documento, notas), o cuando la tipografía y el refinamiento del diseño importan más que calcular números. Renderizado a PNG con headless Chrome/Edge.
• Ambos — mismo plan de diapositiva, dos representaciones.

Indica tu recomendación con la razón (entrada de datos → matplotlib; entrada de texto → HTML). Si no se puede preguntar al usuario (una ejecución automatizada), elige según esa regla y di cuál elegiste y por qué.

Construir la hoja de hechos

Antes de diseñar cualquier cosa, enumera cada hecho que la diapositiva pueda usar. Para cada hecho, registra:

hecho	valor	medido en (qué datos / qué sección)	fuente (archivo + script, o página/tabla del artículo)

Luego:

• Cruza los hechos entre sí y con cualquier texto borrador (una publicación, un resumen, un README). Resuelve cada discrepancia ahora — una diapositiva que dice 38 mientras la publicación dice 36 destruye la confianza, y estas discrepancias generalmente provienen de dos lugares que calculan "el mismo" número de manera diferente (diferente tamaño de muestra, diferente umbral).
• Registra la división de datos: qué se usó para construir el método vs. qué se reservó para probarlo. La diapositiva debe decirlo, porque "¿el resultado se mantiene en datos que nunca vio?" es la primera pregunta que hace un lector técnico.
• Dos modos:
  • Modo datos (resultados, modelos, CSVs, logs existen): el script de dibujo los carga y calcula cada número al momento de renderizar.
  • Modo fuente (solo texto): cada número se copia de la fuente y la hoja de hechos cita dónde (página, tabla, figura). No inventes ni redondees números más allá de lo que indica la fuente.

Guarda la hoja de hechos junto a la diapositiva (<nombre>_facts.md) para que las ediciones posteriores se mantengan consistentes.

Paso 1 — Encontrar la historia (3–6 tarjetas numeradas)

Escribe una oración respondiendo cada pregunta. Cada respuesta se convierte en una tarjeta:

1. Descubrimiento / contexto — qué se notó, o cuál es el escenario.
2. Problema — qué está mal o falta, medido. Si hay varios problemas, nómbralos (Problema A, Problema B). Indica qué se aborda y qué se deliberadamente no se aborda, con la razón — un lector que ve un elemento débil en el gráfico y ninguna explicación asume un error.
3. Método — la receta para un caso, como pasos.
4. De un caso a todos los casos — cómo se aplicó la receta en todas partes, las reglas que decidieron cuántos, y los conteos. Empareja cada arreglo con el problema que resuelve ("Arreglo A → Problema A").
5. Resultado + lección — qué cambió, qué tan seguros estamos, qué enseña.

Fusiona tarjetas que dicen lo mismo (las tarjetas redundantes se eliminaron en cada revisión). Para una entrada pequeña, las tarjetas 3 y 4 pueden fusionarse, o la diapositiva puede tener 3 tarjetas: problema → método → resultado. Nunca más de 6 — más allá de eso es una presentación, no una diapositiva.

Paso 2 — Titular

Una o dos líneas en la parte superior: un hecho sorprendente + la acción tomada, ej. "N de las M partes no estaban haciendo nada. Así que consiguieron un trabajo." El titular es lo que hace que alguien deje de desplazarse; las tarjetas son lo que hace que confíen. Los números del titular provienen de la hoja de hechos / las variables del script, nunca escritos a mano.

Paso 3 — Esqueleto de tarjeta (el mismo para cada tarjeta)

• Número + color de acento. Cada tarjeta tiene un número grande (1–5) y su propio color de acento, usado para su borde y resaltados. Los números dan el orden de lectura; los colores permiten que las tarjetas posteriores apunten hacia atrás ("los 11 detectores de la tarjeta 4").
• Título = la pregunta que responde la tarjeta.
• Una oración de conclusión en negrita = la respuesta.
• Una figura principal. La tarjeta de método puede usar una cuadrícula de celdas de paso; la tarjeta de resultado puede usar un gráfico más un panel de explicación.
• Etiqueta de datos — qué datos usa esta tarjeta y por qué esos datos ("18,000 de 60,000 imágenes de entrenamiento (30%) — el resto se mantuvo oculto para que la verificación final sea justa").
• Nota al pie corta — solo advertencias. El razonamiento nunca va en la nota al pie (ver Paso 4).

Paso 4 — Tarjeta de método: celdas de QUÉ / imagen / POR QUÉ

Divide el método en 3–5 celdas numeradas (una cuadrícula de 2×2 cuando hay 4). Cada celda tiene las mismas tres bandas, de arriba a abajo:

1. Leyenda (QUÉ) — una acción concreta que dice qué se compara con qué: "Compara una imagen NUEVA (una que nunca ha visto) con el patrón del paso 2", no "se empareja".
2. Imagen — construida a partir de ejemplos reales de los datos o la fuente: entradas reales, el resultado intermedio real, puntuaciones reales. Los ejemplos reales son lo que hace que un paso abstracto sea creíble; un icono genérico no enseña nada.
3. Caja POR QUÉ — ancho completo, altura fija, con estilo visible (fondo teñido, etiqueta "¿POR QUÉ?"). Dice por qué funciona el paso.

El POR QUÉ debe estar en la imagen, de manera prominente. En las revisiones, el razonamiento colocado en notas al pie se pasó por alto cada vez y el lector tuvo que preguntar repetidamente. Dentro de las celdas, responde las preguntas que los lectores harán:

• ¿Por qué esta elección en lugar de la obvia? (ej. por qué restar el promedio de la clase correcta)
• ¿Qué NO afecta esto, y por qué no? (ej. "solo puede reducir '3'; si otra clase ya gana, nada cambia")

Muestra el mecanismo como antes → después: un pequeño panel de puntuaciones/estados antes, una flecha, el panel después, con ✓/✗ en el ganador y una nota corta en la flecha ("el segundo más alto gana"). Si un título de panel no cabe debajo, colócalo a un lado.

Si una imagen simplifica la realidad (muestra píxeles, mientras que el cálculo real usa características internas), dilo en la nota al pie — la honestidad sobre la simplificación cuesta una línea y evita un comentario de "así no es como funciona".

Marca un ejemplo trabajado como "Ejemplo:" y establece la regla general ("misma receta para los 30 detectores"), de lo contrario los lectores pensarán que el método solo cubre ese caso.

Paso 5 — Hacer que cada número sea trazable

• Muestra el origen de cada número como una cadena visible: "21 ejemplos → 3 estilos → 3 detectores", "11 + 19 = 30 de 36 (6 sobrantes)". Los totales deben sumar visiblemente, y los sobrantes necesitan una razón.
• Indica las reglas de selección y los umbrales que produjeron los conteos ("un estilo necesita ≥2 ejemplos", "errores con <3 ejemplos omitidos por ser demasiado pocos para aprender").
• Si los datos provienen de diferentes fuentes (etiquetados vs. extraídos, medidos vs. estimados), muéstralo visualmente (barras oscuras vs. claras) con una leyenda.
• Explica cualquier notación la primera vez que aparece ("×N = N detectores de estilo para ese error").
• En modo datos, el script calcula cada número; las cadenas de texto usan las variables (f-strings / valores de plantilla). Los números escritos a mano se desincronizan con los datos — esto causó una diapositiva incorrecta real.

Paso 6 — Resultado honesto, cada cambio explicado

• Antes → después en datos nunca usados para construir el método; confirma en un segundo conjunto no utilizado cuando exista uno.
• Da ganancias y pérdidas ("34 arreglados, 9 rotos"). Un resultado con solo ganancias se lee como seleccionado a dedo.
• Estadísticas en palabras simples ("aproximadamente 6 de un millón por casualidad"), con la forma técnica pequeña o en la nota al pie.
• Un gráfico de cambio por elemento (después − antes, coloreado positivo / negativo / cero) más un panel de "por qué cambió cada uno": por qué ocurrieron las ganancias, por qué ocurrieron las pérdidas, cualquier efecto secundario adicional. Enumerar una pérdida sin su razón invita a la peor interpretación.

Paso 7 — Palabras simples y consistentes

• Define cada término en su primer uso con unas pocas palabras simples, o reemplázalo con una palabra simple.
• Una palabra por concepto en toda la diapositiva ("predicho" en todas partes, nunca a veces "respondido").
• Sin apodos internos ("Conjunto A", "el giro", "efecto secundario afortunado", "×3") a menos que se definan en la diapositiva.
• Cada afirmación debe coincidir con su gráfico. Si el gráfico muestra algo extraño que el texto no aborda, abórdalo.

Paso 8 — Leyendas y color

• Cada color, sombra, flecha y símbolo se explica donde aparece. Las imágenes divergentes obtienen "rojo = solo en X, azul = solo en Y".
• Un significado de color en toda la diapositiva: ej. rojo = problema/eliminado, verde = arreglado/bueno, gris = neutral. Los colores de acento de las tarjetas están separados de estos colores semánticos.
• Los elementos agrupados (estilos de un error, variantes de un paso) se colocan en cajas visibles para que los grupos no se difuminen.

Paso 9 — Banners de conclusión y lección

• Banner de conclusión (tono verde): qué se mostró, incluyendo su tamaño y límites ("ganancia pequeña pero real que se mantiene en datos nuevos").
• Banner de lección (parte inferior de la diapositiva): qué puede llevar el lector a otros problemas.

Paso 10 — Diseño

• 16:9 (ej. 16×9 pulgadas a 150 ppp, o un lienzo de 1600×900 px). Las tarjetas se leen de izquierda a derecha en orden de la historia.
• Tamaño de las tarjetas según el contenido — la tarjeta de método suele ser la más ancha. Sin áreas vacías grandes: si una tarjeta tiene espacio libre, amplía su gráfico o mueve su panel de texto al espacio.
• Sin texto superpuesto; las etiquetas se mantienen dentro de sus cajas. Ajusta las líneas largas en lugar de reducir las fuentes por debajo de la legibilidad en teléfono (≈7.5 pt a 16×9 pulgadas es el mínimo).
• Lee references/matplotlib-recipes.md (PNG) o references/html-recipes.md (HTML) para el código de diseño. scripts/slide_kit.py proporciona ayudantes de matplotlib (tarjetas, celdas de paso, cajas POR QUÉ, paneles de puntuación antes/después, banners, exportación PNG+JPG) — impórtalo en lugar de reescribirlos.

Paso 11 — Renderizar, inspeccionar, arreglar, repetir

1. Renderiza la imagen.
2. Mira la imagen real — abre el PNG y haz zoom en cada tarjeta (recórtala si es necesario). El código que "debería" encajar a menudo no lo hace; las superposiciones y el texto recortado solo son visibles en el renderizado.
3. Revisa references/checklist.md tarjeta por tarjeta, como un ingeniero junior que la ve por primera vez.
4. Arregla, vuelve a renderizar, vuelve a revisar. No muestres al usuario una diapositiva que no pase la lista de verificación.

Paso 12 — Variantes y verificación final

• Versión detallada para lectores técnicos (todos los números). Ofrece una versión simple para una audiencia amplia: misma historia, menos números exactos.
• Exporta una copia JPG (sin transparencia) para LinkedIn/X.
• Verifica cada afirmación o cita externa que aparezca en la diapositiva o en una publicación complementaria antes de publicar; marca cualquier cosa que no hayas podido verificar.
• Entrega: el PNG (+ JPG), el script de dibujo o la fuente HTML, y la hoja de hechos. Menciona que linkedin-arabic-science-post, tweet-post o figure-animator pueden producir una publicación o una versión animada a partir de la diapositiva terminada.