Prática
Notas sobre Escrita de READMEs Técnicos
O que pertence a um README, o que não pertence, e como respeitar o tempo do leitor.
Um README é frequentemente o primeiro e único documento que alguém lê sobre seu projeto. Seu trabalho não é impressionar. Seu trabalho é ajudar alguém a decidir e agir.
Comece com Propósito
O primeiro parágrafo deve responder: O que é isso? Para quem é? Que problema resolve? Pule a história de origem a menos que esclareça o escopo.
Instalação Antes de Arquitetura
Coloque instruções de setup cedo. Se alguém não consegue rodar seu projeto em cinco minutos, não lerá seu diagrama de arquitetura. Inclua pré-requisitos, comandos de instalação e um exemplo mínimo funcional.
Mantenha Material de Referência Escaneável
Use headings, tabelas e blocos de código. Prosa longa pertence a docs separadas. O README deve linkar para material mais profundo, não conter tudo.
Manutenção É Parte da Feature
Um README desatualizado é pior do que nenhum README. Quando você muda passos de setup ou quebra compatibilidade, atualize o README no mesmo commit. Trate como código.