writing-guidelines
Writing Guidelines
Público-Alvo: Este documento fornece padrões de escrita para agentes de IA (LLMs) ao criar documentação, comentários de código e conteúdo técnico para projetos de desenvolvimento Polkadot.
Princípios Fundamentais (Método Zinsser)
Regras de Escrita Comercial
Comece com o resultado, não com o processo
Use voz ativa: "Nós corrigimos o bug" e não "O bug foi corrigido"
Escreva para o leitor que não sabe nada sobre seu trabalho
Declare conclusões primeiro, depois explique se necessário
Uma ideia por frase, um tópico por parágrafo
Escrita Relacionada a Código
Nomes de variáveis são frases: torne-os claros, não espertos
Mensagens de erro devem dizer aos usuários o que fazer em seguida
Documentação deve responder "por quê", código mostra "o quê"
Descrições de PR: Declare mudanças e impactos, pule a jornada
Mensagens de commit: O que mudou e por quê, no tempo presente
Brevidade é poder. Reduza cada frase aos seus componentes mais limpos. Remova toda palavra que não serve função alguma. Substitua frases por palavras. Escolha palavras simples em vez de complexas.
Eliminação de Desordem
Corte qualificadores: "muito", "bastante", "um tanto", "meio que", "praticamente"
Remova pares redundantes: "todos e cada um", "primeiro e principal", "vários e diversos"
Elimine pigarreios: "É importante notar que", "O fato de que"
Evite frases infladas: Use "agora" e não "neste momento no tempo"
Delete jargão sem sentido: "utilizar" → "usar", "implementar" → "fazer"
Comece com o que faz, não como funciona
Use exemplos concretos em vez de descrições abstratas
Escreva instruções como comandos: "Execute testes" e não "Você deveria executar testes"
Teste sua escrita: Alguém consegue seguir sem você estar lá?
Assuma inteligência mas não conhecimento
O Teste Zinsser
Antes de confirmar qualquer texto escrito, pergunte:
Posso cortar esta frase pela metade?
Existe uma palavra mais simples?
O leitor precisa saber isso?
Estou dizendo isso duas vezes?
Última actualización