devemos classificar ele. Por isso, mas não exclusivamente, devemos sempre configurar adequadamente a licença do software, mesmo ele não sendo “aberto”; (O mesmo vale para as dependências das nossas aplicações, fiquem atentos!)
ou time tem acesso ao código; - Saber como o código funciona; - Saber como executar o código; - Saber como testar o código; - Qualquer pessoa ou time pode submeter mudanças;
qualquer projeto precisa de uma motivação para existir e continuar a ser mantido. Essa motivação precisa ser clara e evidente para qualquer um que tiver contato com o código. Como o projeto resolve o problema? Uma descrição clara de qual é a abordagem do projeto facilita o entendimento do próprio código. aquilo que se pretende alcançar quando se realiza uma ação; propósito.
ou lista de quais são as tecnologias usadas no projeto ajuda a entender rapidamente quais as dependências do mesmo e o necessário para ele funcionar. De sistemas de fila a bancos de dados para cache ou dados persistentes, além de referências para libs ou frameworks usados no projeto. Toda informação agrega no aprendizado do próprio projeto. conjunto de tecnologias usadas no projeto
é raro ficar sem entender por onde a informação chega, o que é feito com ela e para onde ela vai. Um desenho explicando isso poupa várias horas de qualquer profissional que está começando no projeto ou voltando para ele. conjunto de elementos que perfazem um todo; estrutura, natureza, organização.
relaciona? Uma breve lista de links de projetos relacionados. Podem ser projetos de qualquer natureza, dependências diretas ou indiretas. Projetos que dependem do projeto atual ou projetos que ele depende. Esse tipo de informação economiza horas de trabalho. capacidade de manter relacionamentos, de conviver bem com seus semelhantes.
“rodar”? Não devemos nunca assumir que quem for trabalhar no projeto conhece determinados comandos ou usa determinadas IDEs, muito menos que conhece a stack do projeto. Uma coleção de comandos simples e úteis para o desenvolvimento do projeto. De testes a build, quanto mais comandos documentados melhor. sequência de passos necessários para automatizar processos
variáveis de ambiente? Há arquivos de configuração? Procuramos sempre criar projetos que não dependam de mudanças no código para que comportamento ou ações também mudem. Para isso existem as configurações. Uma lista delas ou um link para o arquivo onde elas ficam (devidamente comentadas e descritas), ajuda a fácilmente entender boa parte das possibilidades do projeto. ato ou efeito de configurar.
Sejam APis Rest, consumidores ou produtores de eventos, todo projeto possui uma coleção de “contratos”. Há inúmeras formas de se documentar isso. Não importa se a documentação é automática, viva ou estática, ela precisa existir. A documentação da API pode estar no README do projeto ou fora dele, quando for este o caso, novamente, faça referência disso no README do projeto. acordo entre as partes, que se obrigam a cumprir o que foi combinado sob determinadas condições