IbrahimSobh/content-explainer-slide

Content Explainer Slide (Slide Explicativo de Conteúdo)

Cria uma imagem que conta a história de um trabalho técnico: o que foi notado, o que estava errado, o que foi feito e por que cada etapa funciona, de onde vem cada número, e o que foi alcançado e aprendido.

A meta é 100% claro e intuitivo para um engenheiro júnior, não 100% detalhado. Essa meta vem de rodadas reais de revisão: cada vez que um termo não foi definido, um número não tinha origem visível, a razão de uma etapa estava escondida em uma nota de rodapé, ou um cartão tinha uma área vazia, o leitor voltava com "o que é isso?", "de onde veio 30?", "por que isso funciona?" — e o slide precisava de outra rodada. Tudo abaixo existe para responder a essas perguntas no slide antes que o leitor precise perguntar.

Um exemplo prático de um plano de slide finalizado (um experimento de "cirurgia de neurônios" em rede neural) está em references/worked-example.md. Leia-o uma vez antes de planejar seu primeiro slide; ele mostra como cada cartão fica quando as regras são aplicadas.

Etapa 0 — Pergunte o formato de saída e depois crie uma ficha de fatos

Pergunte o formato (uma vez, antes de desenhar)

Pergunte ao usuário qual formato de saída ele deseja, a menos que já tenha dito:

• PNG via matplotlib (Python) — melhor quando a entrada tem dados, modelos, logs ou arquivos de resultado, porque um script pode calcular cada número no slide diretamente desses arquivos (sem números digitados à mão). Também exporta uma cópia JPG.
• Página HTML/SVG renderizada como PNG — melhor quando a entrada é apenas texto (um artigo, um documento, anotações), ou quando a tipografia e o acabamento do layout são mais importantes do que calcular números. Renderizado como PNG com Chrome/Edge headless.
• Ambos — mesmo plano de slide, duas renderizações.

Dê sua recomendação com a justificativa (dados de entrada → matplotlib; texto de entrada → HTML). Se o usuário não puder ser consultado (execução automatizada), escolha por essa regra e diga qual escolheu e por quê.

Crie a ficha de fatos

Antes de projetar qualquer coisa, liste cada fato que o slide pode usar. Para cada fato, registre:

fato	valor	medido em (qual dado / qual seção)	fonte (arquivo + script, ou página/tabela do artigo)

Depois:

• Cruzamento de fatos uns contra os outros e contra qualquer rascunho de texto (um post, um resumo, um README). Resolva cada incompatibilidade agora — um slide que diz 38 enquanto o post diz 36 destrói a confiança, e essas incompatibilidades geralmente vêm de dois lugares calculando "o mesmo" número de forma diferente (tamanho de amostra diferente, limiar diferente).
• Registre a divisão dos dados: o que foi usado para construir o método vs. o que foi retido para testá-lo. O slide deve dizer isso, porque "o resultado se mantém em dados que nunca viu?" é a primeira pergunta que um leitor técnico faz.
• Dois modos:
  • Modo dados (resultados, modelos, CSVs, logs existem): o script de desenho carrega-os e calcula cada número no momento da renderização.
  • Modo fonte (apenas texto): cada número é copiado da fonte e a ficha de fatos cita onde (página, tabela, figura). Não invente ou arredonde números além do que a fonte afirma.

Salve a ficha de fatos ao lado do slide (<nome>_facts.md) para que edições posteriores permaneçam consistentes.

Etapa 1 — Encontre a história (3 a 6 cartões numerados)

Escreva uma frase respondendo a cada pergunta. Cada resposta se torna um cartão:

1. Descoberta / contexto — o que foi notado, ou qual é o cenário.
2. Problema — o que está errado ou faltando, medido. Se houver vários problemas, nomeie-os (Problema A, Problema B). Indique o que é alvo e o que é deliberadamente não alvo, com a razão — um leitor que vê um item fraco no gráfico e sem explicação assume um erro.
3. Método — a receita para um caso, em etapas.
4. De um caso para todos os casos — como a receita foi aplicada em todos os lugares, as regras que decidiram quantos e as contagens. Emparelhe cada correção com o problema que resolve ("Correção A → Problema A").
5. Resultado + lição — o que mudou, o quão certos estamos, o que isso ensina.

Mescle cartões que dizem a mesma coisa (cartões redundantes foram removidos a cada revisão). Para uma entrada pequena, os cartões 3 e 4 podem se fundir, ou o slide pode ter 3 cartões: problema → método → resultado. Nunca mais de 6 — além disso, é um deck, não um slide.

Etapa 2 — Manchete

Uma ou duas linhas no topo: um fato surpreendente + a ação tomada, por exemplo, "N das M peças não faziam nada. Então receberam uma função." A manchete é o que faz alguém parar de rolar; os cartões são o que os faz confiar. Os números da manchete vêm da ficha de fatos / das variáveis do script, nunca digitados à mão.

Etapa 3 — Esqueleto do cartão (igual para todos os cartões)

• Número + cor de destaque. Cada cartão tem um número grande (1–5) e sua própria cor de destaque, usada para sua borda e destaques. Os números dão a ordem de leitura; as cores permitem que cartões posteriores apontem para trás ("os 11 detectores do cartão 4").
• Título = a pergunta que o cartão responde.
• Uma frase de conclusão em negrito = a resposta.
• Uma figura principal. O cartão de método pode usar uma grade de células de etapa; o cartão de resultado pode usar um gráfico mais um painel de explicação.
• Rótulo de dados — quais dados este cartão usa e por que esses dados ("18.000 das 60.000 imagens de treino (30%) — o restante mantido invisível para que a verificação final seja justa").
• Nota de rodapé curta — apenas ressalvas. A fundamentação nunca vai na nota de rodapé (veja Etapa 4).

Etapa 4 — Cartão de método: O QUE / figura / PORQUÊ células

Divida o método em 3 a 5 células numeradas (uma grade 2×2 quando há 4). Cada célula tem as mesmas três faixas, de cima para baixo:

1. Legenda (O QUE) — uma ação concreta que diz o que é comparado com o quê: "Compare uma imagem NOVA (que nunca viu) com o padrão da etapa 2", não "ela é combinada".
2. Figura — construída a partir de exemplos reais dos dados ou da fonte: entradas reais, o resultado intermediário real, pontuações reais. Exemplos reais são o que tornam uma etapa abstrata crível; um ícone genérico não ensina nada.
3. Caixa PORQUÊ — largura total, altura fixa, visualmente estilizada (fundo colorido, rótulo "PORQUÊ?"). Ela diz por que a etapa funciona.

O PORQUÊ deve estar na figura, de forma proeminente. Nas revisões, a fundamentação colocada em notas de rodapé foi ignorada toda vez e o leitor teve que perguntar repetidamente. Dentro das células, responda às perguntas que os leitores farão:

• Por que esta escolha em vez da óbvia? (por exemplo, por que subtrair a média da classe correta)
• O que isso NÃO afeta, e por que não? (por exemplo, "só pode diminuir '3'; se outra classe já vence, nada muda")

Mostre o mecanismo como antes → depois: um pequeno painel de pontuações/estados antes, uma seta, o painel depois, com ✓/✗ no vencedor e uma pequena nota na seta ("o 2º maior vence"). Se o título de um painel não couber abaixo dele, coloque-o ao lado.

Se uma figura simplifica a realidade (mostra pixels, enquanto o cálculo real usa features internas), diga isso na nota de rodapé — honestidade sobre simplificação custa uma linha e evita um comentário "não é assim que funciona".

Marque um exemplo prático como "Exemplo:" e indique a regra geral ("mesma receita para todos os 30 detectores"), caso contrário os leitores pensam que o método cobre apenas aquele caso.

Etapa 5 — Torne cada número rastreável

• Mostre a origem de cada número como uma cadeia visível: "21 exemplos → 3 estilos → 3 detectores", "11 + 19 = 30 de 36 (6 sobrando)". Os totais devem somar visivelmente, e as sobras precisam de uma razão.
• Indique as regras de seleção e limiares que produziram as contagens ("um estilo precisa de ≥2 exemplos", "erros com <3 exemplos ignorados por serem poucos para aprender").
• Se os dados vieram de fontes diferentes (rotulados vs. minerados, medidos vs. estimados), mostre visualmente (barras escuras vs. claras) com uma legenda.
• Explique qualquer notação na primeira vez que aparecer ("×N = N detectores de estilo para aquele erro").
• No modo dados, o script calcula cada número; as strings de texto usam as variáveis (f-strings / valores de template). Números digitados à mão ficam dessincronizados com os dados — isso causou um slide errado real.

Etapa 6 — Resultado honesto, cada mudança explicada

• Antes → depois em dados nunca usados para construir o método; confirme em um segundo conjunto não usado quando existir.
• Dê ganhos e perdas ("34 corrigidos, 9 quebrados"). Um resultado com apenas ganhos parece selecionado a dedo.
• Estatísticas em palavras simples ("cerca de 6 em um milhão por sorte"), com a forma técnica pequena ou na nota de rodapé.
• Um gráfico de mudança por item (depois − antes, colorido positivo / negativo / zero) mais um painel "por que cada um mudou": por que os ganhos ocorreram, por que as perdas ocorreram, qualquer efeito colateral bônus. Listar uma perda sem sua razão convida à pior interpretação.

Etapa 7 — Palavras simples e consistentes

• Defina cada termo no primeiro uso com algumas palavras simples, ou substitua-o por uma palavra simples.
• Uma palavra por conceito em todo o slide ("previsto" em todos os lugares, nunca às vezes "respondido").
• Sem apelidos internos ("Conjunto A", "a reviravolta", "efeito colateral sortudo", "×3") a menos que definidos no slide.
• Cada afirmação deve corresponder ao seu gráfico. Se o gráfico mostra algo estranho que o texto não aborda, aborde-o.

Etapa 8 — Legendas e cores

• Cada cor, tom, seta e símbolo é explicado onde aparece. Imagens divergentes recebem "vermelho = apenas em X, azul = apenas em Y".
• Um significado de cor em todo o slide: por exemplo, vermelho = problema/removido, verde = corrigido/bom, cinza = neutro. As cores de destaque dos cartões são separadas dessas cores semânticas.
• Itens agrupados (estilos de um erro, variantes de uma etapa) ficam em caixas visíveis para que os grupos não se misturem.

Etapa 9 — Banners de conclusão e lição

• Banner de conclusão (tom verde): o que foi mostrado, incluindo seu tamanho e limites ("ganho pequeno mas real que se mantém em novos dados").
• Banner de lição (parte inferior do slide): o que o leitor pode levar para outros problemas.

Etapa 10 — Layout

• 16:9 (por exemplo, 16×9 polegadas a 150 dpi, ou uma tela de 1600×900 px). Os cartões são lidos da esquerda para a direita na ordem da história.
• Dimensione os cartões pelo conteúdo — o cartão de método geralmente é o mais largo. Sem grandes áreas vazias: se um cartão tiver espaço sobrando, aumente seu gráfico ou mova seu painel de texto para o espaço.
• Sem texto sobreposto; os rótulos permanecem dentro de suas caixas. Quebre linhas longas em vez de encolher fontes abaixo da legibilidade em telefone (≈7,5 pt a 16×9 pol é o mínimo).
• Leia references/matplotlib-recipes.md (PNG) ou references/html-recipes.md (HTML) para código de layout. scripts/slide_kit.py fornece ajudantes matplotlib (cartões, células de etapa, caixas PORQUÊ, painéis de pontuação antes/depois, banners, exportação PNG+JPG) — importe-o em vez de reescrevê-los.

Etapa 11 — Renderize, inspecione, corrija, repita

1. Renderize a imagem.
2. Olhe a imagem real — abra o PNG e dê zoom em cada cartão (recorte-o, se necessário). Código que "deveria" caber muitas vezes não cabe; sobreposições e texto cortado só são visíveis na renderização.
3. Percorra references/checklist.md cartão por cartão, como um engenheiro júnior vendo-o pela primeira vez.
4. Corrija, renderize novamente, verifique novamente. Não mostre ao usuário um slide que falhe na checklist.

Etapa 12 — Variantes e verificação final

• Versão detalhada para leitores técnicos (todos os números). Ofereça uma versão simples para um público amplo: mesma história, menos números exatos.
• Exporte uma cópia JPG (sem transparência) para LinkedIn/X.
• Verifique cada afirmação ou citação externa que aparece no slide ou em um post complementar antes de publicar; sinalize qualquer uma que você não pôde verificar.
• Entregue: o PNG (+ JPG), o script de desenho ou fonte HTML, e a ficha de fatos. Mencione que linkedin-arabic-science-post, tweet-post ou figure-animator podem produzir um post ou uma versão animada a partir do slide finalizado.