Licenças!! As licenças atreladas ao código e software determinam como 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!)
“conjunto de padrões de comportamento, crenças, conhecimentos, costumes etc. que distinguem um grupo social.” Entendemos como cultura open source um conjunto de comportamentos e formas de como o código/software é gerenciado.
Cultura Open Source dentro de uma empresa; - Qualquer pessoa 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;
Documentar nem sempre é uma tarefa fácil. É necessário dedicação para não apenas manter a documentação atualizada, como também encontrar formas de dar clareza sobre tudo relacionado ao projeto. Documentação
Documentação > Objetivo Por quê este projeto existe? Todo e 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.
Documentação > Stack Qual a stack do projeto? Uma descrição 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
Documentação > Infra/Arquitetura Esquema de funcionamento Fluxo da informação Não é 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.
Documentação > Relacionamentos Com quais outros projetos este projeto se 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.
Documentação > Fluxo de trabalho Como fazemos para o projeto “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
Documentação > Configuração Quais as opções deste projeto? Quais as 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.
Documentação > API Quais os endpoints e contratos do projeto? 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