Faça um README
sugestões para um bom README
cada projecto é diferente, por isso considere qual destas secções se aplica ao seu. As secções utilizadas no modelo são sugestões para a maioria dos projectos de código aberto. Também tenha em mente que enquanto um README pode ser muito longo e detalhado, muito longo é melhor do que muito curto. Se você acha que seu README é muito longo, considere a utilização de outra forma de documentação em vez de cortar a informação.
nome
escolha um nome auto-explicativo para o seu projecto.,
Descrição
deixe as pessoas saberem o que o seu projecto pode fazer especificamente. Fornecer o contexto e adicionar um link para qualquer visitante de referência pode não estar familiarizado com. Uma lista de características ou uma subseção de fundo também pode ser adicionado aqui. Se houver alternativas ao seu projeto, este é um bom lugar para listar fatores diferenciadores.
crachás
em algumas leituras, poderá ver pequenas imagens que transmitem metadados, como se todos os testes estão ou não a passar para o projecto. Você pode usar escudos para adicionar um pouco ao seu README. Muitos serviços também têm instruções para adicionar um crachá.,
visuais
dependendo do que você está fazendo, pode ser uma boa idéia incluir screenshots ou até mesmo um vídeo (você”verá frequentemente GIFs em vez de vídeos reais). Ferramentas como ttygif podem ajudar, mas confira Asciinema para um método mais sofisticado.
instalação
dentro de um ecossistema particular, pode haver uma maneira comum de instalar as coisas, tais como usando fios, NuGet, ou Homebrew. No entanto, considere a possibilidade de que quem está lendo seu README é um novato e gostaria de mais orientação., Listar passos específicos ajuda a remover a ambiguidade e leva as pessoas a usar o seu projeto o mais rápido possível. Se ele só funciona em um contexto específico como uma determinada versão de linguagem de programação ou sistema operacional ou tem dependências que têm de ser instaladas manualmente, também adicione uma subseção de requisitos.
use
Use exemplos liberalmente, e mostre a saída esperada se puder. É útil ter em linha o menor exemplo de uso que você pode demonstrar, ao mesmo tempo fornecendo links para exemplos mais sofisticados se eles são muito longos para razoavelmente incluir no README.,
suporte
diga às pessoas para onde podem ir para pedir ajuda. Pode ser qualquer combinação de um rastreador de problemas, uma sala de chat, um endereço de E-mail, etc.
roteiro
Se você tem idéias para lançamentos no futuro, é uma boa idéia listá-los no README.
contribuição
Estado se você está aberto a contribuições e quais são as suas exigências para aceitá-las.
para as pessoas que querem fazer alterações ao seu projecto, é útil ter alguma documentação sobre como começar., Talvez haja um script que eles devem executar ou algumas variáveis de ambiente que eles precisam definir. Torne estes passos explícitos. Estas instruções também podem ser úteis para o seu futuro eu.
Você também pode documentar comandos para manchar o código ou executar testes. Estes passos ajudam a garantir alta qualidade de código e reduzir a probabilidade de que as mudanças inadvertidamente quebram algo. Ter instruções para executar testes é especialmente útil se requer configuração externa, como iniciar um servidor de selênio para testar em um navegador.,
autores e agradecimentos
mostra a sua apreciação para aqueles que contribuíram para o projecto.
licença
para projetos de código aberto, diga como ele é licenciado.
Estado do projecto
Se tiver ficado sem energia ou tempo para o seu projecto, coloque uma nota no topo do README dizendo que o desenvolvimento abrandou ou parou completamente. Alguém pode optar por bifurcar o seu projecto ou voluntariar-se para intervir como mantenedor ou proprietário, permitindo que o seu projecto continue. Você também pode fazer um pedido explícito para mantenedores.