Como escrever um README para o seu projeto

O README é a primeira coisa que quase todo mundo vê ao abrir um repositório. A documentação do GitHub diz que ele deve contar o que o projeto faz, por que é útil, como começar, onde pedir ajuda e quem o mantém. A Open Source Guides chega às quatro primeiras perguntas por outro caminho (o que faz, por que é útil, como começar, onde obter ajuda) e acrescenta que o arquivo também pode falar de como contribuições são tratadas, dos objetivos do projeto e da licença.

A Open Source Guides lembra que quem lê não é quem escreveu: quem chega pode ter uma experiência bem diferente da sua. Evite supor que a pessoa já sabe o que é o projeto, o que ele substitui ou qual ferramenta ele exige. Escreva o primeiro parágrafo para alguém que nunca ouviu falar dele.

A página também desfaz uma desculpa comum: não pular o README porque o projeto ainda não está pronto, ou porque você não quer contribuições. Esses são justamente motivos para escrever um README que diga isso.

1. Nome e uma frase que diz o que o projeto faz.
2. Por que usar: o problema que resolve.
3. Instalação: comandos que a pessoa copia e cola. Diga a versão exigida do runtime.
4. Uso: o menor exemplo que funciona.
5. Onde pedir ajuda: issues, discussões, e-mail.
6. Como contribuir: um link para o CONTRIBUTING.md.
7. Licença: o nome e um link para o arquivo LICENSE. A Open Source Guides é taxativa: um projeto aberto deve ter licença desde o lançamento.
8. Quem mantém.

O gerador de README monta exatamente essa ordem a partir de um formulário e avisa o que faltou.

Segundo o GitHub, o README pode ficar em .github, na raiz ou em docs; havendo mais de um, aparece o de .github, depois o da raiz, depois o de docs. O conteúdo acima de 500 KiB é cortado na visualização do GitHub, então um README gigante precisa virar páginas à parte. Prefira links relativos (docs/instalacao.md, ./LICENSE) e caminhos de imagem relativos: eles continuam funcionando em outras branches e em clones. Caminhos começando com / partem da raiz do repositório, e ./ e ../ também valem. Mantenha o texto de cada link em uma linha só.

# listaki

Guarda suas tarefas em um arquivo de texto, pelo terminal.

## Instalação

    npm install -g listaki

## Uso

    listaki add "escrever o README"
    listaki list

## Ajuda

Abra uma issue descrevendo o que você tentou e o que apareceu.

## Contribuir

Veja o [CONTRIBUTING.md](CONTRIBUTING.md).

## Licença

MIT. Veja o arquivo [LICENSE](LICENSE).

Com 20 linhas, ele já responde o que faz, como começar, onde pedir ajuda, como contribuir e sob qual licença. Quem mantém aparece quando o projeto cresce; a escolha da licença é assunto do codigolivre.dev, que explica cada uma.