Escreva artigos e tutoriais técnicos com exemplos de código executáveis

## Escreva como um engenheiro experiente explicando aos colegas Escreva como uma pessoa experiente em engenharia resolvendo um problema com colegas diante de um quadro: com precisão técnica, franqueza, cordialidade e sem rigidez. Respeite a inteligência do leitor sem presumir que ele já sabe tudo. Explique o que funciona, o que não funciona e por quê. Use expressões inclusivas como “nós” e “vamos analisar” quando elas transformarem o leitor em colaborador. Vá rapidamente ao ponto, deixe que os exemplos sustentem grande parte da explicação e mantenha uma voz confiante sem se tornar moralista. ## Comece por um problema real e mostre cedo código que funcione Abra cada seção com uma a três frases que orientem o leitor e passe, em seguida, ao conteúdo principal. Motive o tópico com uma tarefa, uma falha ou uma carga operacional real, não com uma promessa abstrata. Apresente o código junto com o conceito ou logo depois. Prefira exemplos reais e executáveis a pseudocódigo e explique o comportamento importante depois que o leitor puder vê-lo. Use ferramentas específicas, comandos reais e mensagens de erro representativas, em vez de referências vagas a uma solução genérica. ## Use parágrafos curtos e frases ativas e diretas Limite os parágrafos a cerca de três ou quatro frases. Transfira informações densas para listas ou blocos de código em vez de criar paredes de texto. Una ideias relacionadas com `and` ou `but` com mais frequência do que com ponto e vírgula e use travessões para observações breves em vez de acumular parênteses. Use a voz ativa sempre que funcionar. Empregue o modo imperativo nas instruções e o presente para descrever comportamentos. Em inglês, prefira contrações naturais como `we'll`, `you're`, `it's` e `don't`; use as formas completas somente para dar ênfase deliberada. ## Ligue temas relacionados e pré-requisitos sem explicar demais Use termos técnicos com precisão e apresente-os naturalmente. Não acrescente definições no estilo de glossário, a menos que o termo realmente precise delas. Se um tópico tiver um pré-requisito, indique seu nome e forneça um link para o material relacionado. Use referências cruzadas como pistas que conectem a explicação atual a tópicos anteriores e posteriores. Dê crédito a ferramentas, projetos e pessoas mencionando seus nomes e use links inline descritivos em vez de “clique aqui”. Quando uma ferramenta tiver mais opções do que o artigo puder abordar, direcione o leitor à documentação oficial. ## Recomende com clareza, apoiado na experiência e nos prós e contras Recomende práticas diretamente e sustente-as com experiência, evidências ou uma consideração concreta de vantagens e custos. Não enfraqueça orientações úteis com uma sequência de ressalvas. Ao discutir alternativas, apresente benefícios, custos e condições de forma justa. Use perguntas retóricas com moderação e responda a elas imediatamente. Deixe que um humor contido ou uma expressão ocasionalmente divertida acrescente personalidade sem virar gíria. Demonstre entusiasmo genuíno quando houver motivo, especialmente ao apresentar um workflow útil ou uma possibilidade futura. Transições recorrentes como `Let's look at...`, `The real difference is...` ou `Pro tip:` podem reforçar a voz, mas use-as somente quando fizerem a explicação avançar. ## Corte o enchimento e o tom informal forçado Nunca publique palavrões, emojis, longas histórias pessoais, digressões autobiográficas, gírias nem linguagem informal forçada. Evite clichês sobre um mundo em rápida mudança, convites para “mergulhar fundo”, despedidas vazias, `lol` e o uso de ALL CAPS para dar ênfase. Remova buzzwords, frases de preenchimento sem informação, introduções excessivamente longas, voz passiva desnecessária e linguagem inflada. Em inglês, use `use` em vez de `utilize`. Apresente o ponto diretamente, em vez de escrever `please note that` ou `it is important to note that`. Não explique em excesso o que um leitor do nível previsto já deveria saber. ## Padronize títulos e blocos de código para uma leitura rápida Reserve H1 para o título do documento. Use H2 para as seções principais e H3 para as subseções. Inclua um identificador de linguagem em cada bloco de código e prefira exemplos que os leitores possam executar. Use negrito para um termo-chave em sua primeira apresentação ou para dar ênfase dentro de uma lista, mas nunca coloque uma frase inteira em negrito. Use itálico para observações breves, títulos de obras ou ênfase suave. Coloque uma linha horizontal somente antes de uma seção de encerramento ou assinatura. Escreva links descritivos, mantenha as listas com estrutura paralela e posicione os exemplos perto do texto que sustentam. Use a vírgula de Oxford de forma consistente. ## Organize tutoriais e artigos: problema, código e próximo passo Para uma lição ou tutorial: 1. apresente em uma frase o que o leitor aprenderá; 2. forneça no máximo duas ou três frases de contexto ou motivação; 3. ensine o conteúdo principal com exemplos de código; 4. conecte a lição a tópicos relacionados; 5. convide o leitor a contribuir, fazer perguntas ou continuar aprendendo. Para um post de blog ou artigo, comece com um problema ou uma oportunidade breve, explique por que isso é relevante agora, apresente o percurso principal com código, configuração ou processo, explore implicações mais amplas ou usos adicionais e encerre com um resumo voltado ao futuro e um convite à participação. ## Ajuste o tom para iniciantes e para apresentar ferramentas novas Use uma voz acolhedora, paciente e colaborativa ao explicar um conceito a um iniciante. Ao apresentar uma ferramenta ou um workflow, demonstre entusiasmo e praticidade, mas seja honesto sobre suas limitações. Recomende práticas diretamente e sustente-as com experiência. Discuta as escolhas de forma justa e indique vantagens e desvantagens concretas. Escreva sobre planos futuros com otimismo fundamentado. Mantenha as conclusões concisas, indique a próxima ação útil e faça com que a participação pareça bem-vinda. ## Revise no fim exemplos e links e termine com um próximo passo Confirme que o texto começa com um problema prático, chega rapidamente a um exemplo real e explica em vez de apenas afirmar. Verifique se pré-requisitos e referências cruzadas estão presentes, se os termos técnicos permanecem precisos, se os exemplos são executáveis e se as ferramentas mencionadas recebem o devido crédito. Corte o preenchimento, o jargão desnecessário, as introduções repetidas e as explicações que ultrapassem as necessidades do público-alvo. Verifique títulos, identificadores de linguagem dos blocos de código, links, ênfase, tamanho dos parágrafos e pontuação. Termine com impulso para avançar: o que experimentar, o que observar ou onde continuar.