Um README deve ajudar um novo leitor a dar o primeiro passo útil. Não precisa explicar todos os detalhes de implementação antes de a pessoa entender o que o projeto faz ou se é relevante para ela.

Comece pelo resultado

Descreva o que o projeto faz, para quem é e seus limites importantes. Um exemplo concreto é mais útil que uma lista de adjetivos. Coloque uma captura de tela funcional ou um resultado de exemplo perto do início quando ajudar a explicar o propósito.

Depois, declare os pré-requisitos: sistema operacional, versão do ambiente de execução e serviços necessários. Diferencie integrações opcionais do que é preciso para começar. Não deixe o leitor descobrir um requisito essencial no meio da instalação.

Ofereça um caminho completo para o sucesso

Escreva as etapas de configuração na ordem em que precisam acontecer. Explique onde executar os comandos e como é um resultado bem-sucedido. Use configurações fictícias com clareza e nunca inclua credenciais reais no exemplo.

Teste as instruções a partir de uma cópia limpa do repositório ou ponto de partida equivalente. Um comando que só funciona porque sua máquina tem uma ferramenta não documentada instalada revela uma lacuna na documentação. Mantenha as variações opcionais abaixo do caminho aceito mais simples.

Facilite encontrar o próximo passo

Adicione os comandos comuns para executar, verificar e atualizar o projeto. Vincule documentação mais aprofundada em vez de colocar todos os assuntos especializados na abertura. Inclua o local aceito para relatar problemas e a licença quando relevante.

Use o MeatPad para editar o README junto dos arquivos do projeto e confira seu Markdown renderizado no destino. Siga links e inspecione imagens com os caminhos reais do repositório. Quando a configuração mudar, atualize o README na mesma alteração para que as instruções iniciais descrevam a versão que as pessoas recebem.

Fontes e detalhes do produto

Comece com uma nota. O MeatPad dá às notas, ao Markdown e aos arquivos de projeto uma área de trabalho local no seu Mac, sem exigir uma conta.

Explorar MeatPad →