Ryuketsukami/explicação-simples

Habilidade de Explicação Simples (HES)

Dê a resposta primeiro, em palavras simples. Adicione profundidade em camadas que o leitor pode pular. Nunca troque a verdade pela simplicidade.

A forma: resposta, depois mecânica, depois detalhes

Ordene a explicação pelo que o leitor precisa, não por como você aprendeu:

1. A resposta. Uma ou duas frases simples que respondam diretamente à pergunta ou apresentem o ponto. Um leitor que para aqui tem uma imagem correta — menor, nunca errada.
2. Como e por quê. A mecânica por trás da resposta: a causa, a estrutura, a regra em ação.
3. Os detalhes. Números, parâmetros, casos extremos, exceções, provas. A parte que a maioria dos leitores pula — e que ainda deve estar lá quando alguém voltar para buscá-la.

Mantenha a forma com estas regras:

• Termine cada camada antes de começar a próxima. Nunca misture resumo e detalhe.
• Torne as camadas visíveis e puláveis: uma quebra de parágrafo, um destaque em negrito, um rótulo, um título ou um expansor quando o meio suportar.
• Uma ressalva que mude a resposta pertence ao lado da resposta. Riscos de segurança, perda de dados, mudanças críticas e custos reais nunca ficam em uma camada inferior.
• Passos permanecem em ordem de dependência. Organize a prosa em torno de um procedimento — resultado e pré-condições primeiro, depois os passos numerados, depois os casos de falha — mas nunca reordene os passos por importância.
• A profundidade segue a pergunta. Uma resposta de chat pode precisar de uma camada; um documento de design pode precisar de quatro. Nunca aumente uma explicação para preencher a forma.

As palavras

• Comece com o ator e o verbo: "o cache retorna dados obsoletos", não "dados obsoletos podem ser retornados".
• Use um nome para uma coisa, o mesmo nome todas as vezes. Trocar nomes parece trocar de coisas.
• Prefira a palavra curta e comum: use, comece, ajude, mostre — não utilize, inicie, facilite, demonstre.
• Coloque uma ideia em cada frase. Trate 20 palavras como um limite; divida em vez de empilhar orações.
• Coloque a condição antes da ação: "Se a compilação falhar, verifique o lockfile" — não o contrário.
• Defina um termo em meia frase onde o leitor o encontrar. Não coloque contexto prévio.
• Transforme substantivos abstratos de volta em verbos: "analise o log", não "realize uma análise do log".
• Corte enchimentos, intensificadores e elogios vazios: muito, robusto, contínuo, poderoso, abrangente, "é importante notar".
• Dê números em vez de adjetivos: "de 40 s para 6 s" vence "drasticamente mais rápido".

O piso: simples, nunca menos verdadeiro

• Mantenha todos os fatos, números, advertências e ressalvas. Simplificar move detalhes para uma camada inferior; nunca os deleta.
• Não invente exemplos, evidências ou confiança que a fonte não tenha. Quando algo é desconhecido, diga isso claramente.
• Trate uma analogia como uma ponte, não uma prova. Se o leitor for se apoiar nela, diga onde ela falha.
• Quando simplicidade e precisão entrarem em conflito, a precisão vence — então continue trabalhando para tornar a versão precisa simples.

Exemplo

Antes — verdadeiro, completo, difícil de usar:

Uma transação é uma sequência de instruções tratadas como uma unidade indivisível de trabalho — iniciada implicitamente na primeira instrução e encerrada por COMMIT ou ROLLBACK — um construto que importa porque muitas operações de múltiplos passos só são corretas quando executadas atomicamente.

Depois — os mesmos fatos, em camadas:

Uma transação é um grupo de instruções que todas são bem-sucedidas ou todas falham juntas.

Ela começa na primeira instrução e termina com COMMIT (manter as alterações) ou ROLLBACK (desfazê-las).

O agrupamento importa porque algumas operações só são corretas como um todo: uma transferência que debita uma conta sem creditar a outra deixaria dinheiro faltando.

Verifique antes de entregar

• A primeira frase responde à pergunta?
• O leitor pode parar após qualquer camada e ainda estar correto?
• Advertências e ressalvas que mudam a resposta estão na camada superior?
• Uma palavra mais curta e comum manteria o significado em algum lugar?
• Todos os fatos, números e ressalvas sobreviveram?