Escrever capítulos para o site de um curso que expliquem o porquê antes da fórmula

## Saber onde ficam as páginas do curso e suas traduções O projeto é um site de documentação estático construído a partir de arquivos-fonte do repositório. Mantenha a árvore previsível para que um colaborador consiga adivinhar onde cada coisa fica: - `docs/` — o conteúdo do curso que se transforma nas páginas publicadas. - O diretório de configuração do site dentro da árvore de conteúdo — configuração e sobrescritas de tema para o gerador de site estático. - `docs/public/` — recursos estáticos copiados literalmente para o site final. - Um diretório por idioma adicional dentro da árvore de conteúdo — árvores de tradução que espelham a estrutura do idioma principal. Páginas-esboço são marcadores de posição aceitáveis em uma árvore de tradução. - `code/` — experimentos executáveis alinhados capítulo a capítulo com o texto. - `scripts/` — scripts de manutenção do repositório, como geração de sitemap, verificação e otimização de recursos. - O diretório do fluxo de trabalho de CI — o pipeline que constrói e publica o site. Material novo vai dentro do diretório de conteúdo. As entradas de navegação e da barra lateral são declaradas no arquivo de configuração do site, nunca inferidas apenas pela localização dos arquivos. ## Ver e checar o site localmente com os comandos do projeto Trabalhe pelos próprios pontos de entrada de script do projeto, em vez de chamar as ferramentas subjacentes diretamente, para que todos executem o mesmo pipeline. Um site de documentação com esse formato expõe um conjunto pequeno e fixo deles: - `npm install` — instala as dependências. - `npm run dev` — servidor de desenvolvimento com otimização de recursos. - `npm run dev:fast` — servidor de desenvolvimento que pula a otimização de recursos, para uma inicialização muito mais rápida. - `npm run build` — produz a saída publicável. - `npm run preview` — serve a saída construída exatamente como ela será publicada. - `npm run verify` — verificações de consistência em todo o repositório. - `npm run assets:optimize` — comprime e converte imagens. Use a variante rápida de desenvolvimento enquanto edita o texto, situação em que a otimização de imagens não muda nada daquilo que você está olhando. Use `build` seguido de `preview` quando precisar ver a saída exatamente como ela será publicada. `verify` é a barreira descrita na próxima parte, e `assets:optimize` é executado depois de adicionar imagens, para que originais grandes nunca cheguem ao site publicado. ## Atualizar o menu de cada idioma e checar antes de publicar - Mantenha cada mudança restrita à tarefa em questão. Não reescreva documentos ou configurações sem relação com ela apenas por estar passando por eles. - Prefira adicionar material novo de curso dentro do diretório de conteúdo a reestruturar material que já existe. - Registre as páginas novas na configuração de navegação e da barra lateral quando as adicionar. - Quando uma página for adicionada, movida ou renomeada, atualize a barra lateral de todas as árvores de idioma que a espelham, e não apenas a do idioma principal. Uma árvore de tradução deixada para trás produz uma entrada morta ou uma página faltando. - Execute o comando de verificação antes de fazer push sempre que a configuração, o tema ou os scripts de build tiverem sido tocados. Um push publica o site, então um build não verificado o quebra em público. ## Criar diagramas com fórmulas em LaTeX e convertê-los em SVG Figuras em estilo acadêmico com composição matemática de verdade são escritas como código-fonte, não desenhadas à mão: 1. Escreva o diagrama como um documento independente em uma linguagem de diagramas vetoriais — por exemplo, um documento LaTeX standalone usando um pacote no estilo TikZ. Copie o estilo de uma figura já existente no repositório, em vez de inventar um novo. 2. Compile o código-fonte com um motor LaTeX que suporte as fontes que você usa e, em seguida, converta o PDF resultante em SVG com um conversor de PDF para SVG. Ambas as etapas são ferramentas de linha de comando, então qualquer figura pode ser reconstruída a partir de seu código-fonte a qualquer momento. 3. Mantenha tanto o arquivo-fonte quanto o SVG gerado no mesmo diretório `images/`, ao lado do capítulo que os utiliza, para que a figura continue reproduzível. 4. Referencie o SVG gerado a partir da página markdown por caminho relativo. Mantenha um único estilo visual em todas as figuras: caixas de cantos arredondados com preenchimento bem claro e traço cinza-escuro, um único estilo de ponta de seta, uma fonte de texto igual à do corpo do texto e delimitadores de matemática em linha para os símbolos. ## Escrever com voz de aula paciente, não em tom de bate-papo - Escreva os capítulos como material de tutorial e de aula, não como notas de referência sucintas. - Mantenha uma voz de aula guiada: conversacional, paciente e orientada a problemas. Frases que entregam ao leitor o próximo passo — "Vamos começar pela intuição", "Olhe para isso por outro ângulo", "O que esta etapa significa é…", "A questão real é…" — são bem-vindas, enquanto o tom permanece sério e preciso. - Não escorregue para uma fraseologia de bate-papo, de assistente ou de internet casual. O registro-alvo é o de um capítulo de livro-texto bem acabado. - Ritme os parágrafos de modo que possam ser lidos em voz alta ou trabalhados sozinho. Se um parágrafo não puder ser acompanhado na velocidade de leitura, divida-o. ## Explicar todo o raciocínio e não escrever frases de enchimento Profundidade e economia andam juntas: explique toda a cadeia de raciocínio e não gaste palavra alguma com nada que esteja fora dessa cadeia. - Explique progressivamente — primeiro a intuição, depois a definição formal, depois o código ou a prática. - Dê o contexto e o motivo pelo qual uma etapa é necessária. Não comprima um capítulo em uma lista crua de resultados. - Corte o enchimento condutor. Uma frase que anuncia uma explicação em vez de dá-la ("um exemplo tornará isto mais intuitivo") é apagada, e o exemplo ou a fórmula é apresentado diretamente. - Diga cada coisa uma única vez. Não reafirme o mesmo ponto com outras palavras. - Substitua qualificadores vagos por afirmações causais precisas. Substitutos metafóricos ("isto é mais ou menos equivalente a…") e conectivos evasivos pertencem apenas a um primeiro rascunho. - Evite frases-resumo em estilo de slogan que comprimem um mecanismo em uma expressão de efeito. Enuncie o mecanismo concreto no lugar delas. - Evite listas de erros paralelos com som de máquina ("a consulta era ampla demais, sem comparação de preços, nível de estoque errado, parâmetro errado"). Descreva o processo e mostre como um estado errado que surge cedo se propaga para as ações posteriores. - Evite o padrão de contraste "não A, mas B"; ele soa indireto. Enuncie a afirmação positiva e depois explique por que ela vale. ## Ordenar as ideias para que cada passo novo venha com seu motivo - Siga a linha causal. Não fique circulando o mesmo ponto ao resumir, reafirmar e depois contrastar. Escreva na ordem em que a ideia de fato muda: uma nova capacidade ou configuração aparece, ela altera o objeto de treinamento ou o objeto do problema, e isso torna uma nova formulação possível ou inevitável. - Ao abrir um novo conceito, prefira o formato "agora que X existe, o sistema faz Y, então Z se torna possível (ou necessário)". - Abra uma seção conectando-a com o que o leitor já sabe e, então, nomeie o novo problema que essa seção resolve. - Não faça referências a capítulos anteriores, a menos que a referência seja necessária para a frase imediatamente seguinte. - Dê a cada etapa conceitual uma transição. Nunca salte direto de uma definição para uma fórmula, um termo, um algoritmo ou uma conclusão; diga por que a próxima ideia é necessária antes de apresentá-la. - Não escreva páginas em estilo de enciclopédia que apenas listam definições. Uma definição chega depois de sua motivação e é seguida de uma interpretação. - Deixe os parágrafos correrem da pergunta à resposta. Uma seção bem construída costuma seguir o ritmo: exemplo familiar → tensão ou confusão → ferramenta formal → exemplo resolvido → lição. ## Mostrar um exemplo conhecido antes da fórmula e explicar cada símbolo - Antes de apresentar uma fórmula ou um algoritmo, enuncie o problema que ele resolve; só então mostre a notação. - Mantenha a fórmula ao lado de seu significado: explique cada símbolo importante e depois reformule a fórmula inteira em linguagem simples. - Recorra a uma cena concreta antes de uma abstração. Situações pequenas e familiares — uma tarefa de controle de equilíbrio de uma haste, um bandido multiarmado, geração de texto, uma tarefa de jogo, uma escolha do dia a dia — devem fazer um conceito parecer necessário antes de ele ser nomeado. - Inclua pequenas derivações em vez de afirmar resultados, e mantenha o texto voltado ao aprendiz do início ao fim. - Escreva os termos técnicos no idioma principal do texto sempre que existir um equivalente consagrado, em vez de deixar a palavra emprestada do inglês sem tradução. Mantenha um termo em inglês apenas quando for uma sigla padrão ou quando o título do capítulo exigir, e explique-o na primeira ocorrência. - Use uma única palavra fixa por conceito ao longo de todo o curso. Um sinônimo que varia de capítulo para capítulo é lido pelo aprendiz como um segundo conceito. ## Usar seções curtas com títulos e começar cada commit com feat:, fix: etc. - Use seções curtas com títulos explícitos, em vez de longas corridas de texto sem divisão. - Use negrito com parcimônia, para marcar uma virada conceitual — nunca como decoração. - Use kebab-case para os caminhos dentro do diretório de conteúdo. - Prefira rotas baseadas em diretório com um `index.md` dentro, para que um tópico possa crescer para várias páginas sem mudar sua URL. - Use Conventional Commits em toda mudança: `feat:`, `fix:`, `docs:`, `chore:` e assim por diante.