5 dicas para tornar a documentação uma prioridade em projetos de código aberto

A documentação é tão importante quanto o código, portanto, trate-a dessa maneira. Veja como.

O software de código aberto agora é popular; Já se foi o tempo em que os projetos de código aberto atraíam apenas os desenvolvedores. Hoje em dia, usuários de vários setores são consumidores ativos de software de código aberto e não se pode esperar que todos saibam como usar o software apenas lendo o código.

Mesmo para desenvolvedores (incluindo aqueles com muita experiência em outros projetos de código aberto), uma boa documentação serve como uma valiosa ferramenta de integração quando as pessoas ingressam em uma comunidade. As pessoas interessadas em contribuir para um projeto geralmente começam trabalhando na documentação para se familiarizarem com o projeto, a comunidade e o fluxo de trabalho da comunidade.

Desafios comuns com documentação em código aberto

Embora todos concordem que a documentação é importante e precisa ser feita, algumas das formas como a fazemos resultam em baixa qualidade e falta de consistência entre diferentes partes da documentação do projeto. Por exemplo, quando os desenvolvedores estão muito focados no código, eles não começam a trabalhar na documentação até o último minuto (por exemplo, logo antes do lançamento). E muitas vezes as tarefas de documentação são realizadas por voluntários, pessoas que têm dificuldade em dizer “não”. Para piorar as coisas, as pessoas podem esquecer a documentação após o lançamento, nunca a alterando ou melhorando, e o ciclo vicioso se repete.

5 melhores práticas

Estivemos envolvidos na documentação de vários projetos de código aberto na Linux Foundation Networking e no GitLab nos últimos anos. Abaixo, compartilhamos algumas coisas que aprendemos e esperamos que ajudem a tornar a documentação um cidadão de primeira classe em seu projeto de código aberto.

1. Contribuições de valor para documentação tanto quanto contribuições de código: Grande parte do foco em muitas comunidades de código aberto tende a ser no código. Uma maneira fácil de garantir que as contribuições de documentação sejam valorizadas por todos é dar crédito igual à documentação e ao código nas métricas da sua comunidade. Não importa se um commit, uma solicitação de mesclagem ou uma solicitação pull é para código ou documentação. Além disso, ao fazer o reconhecimento da comunidade, inclua as principais realizações das pessoas que contribuem para a documentação.

2. Coloque a documentação e o código no mesmo repositório do projeto: É altamente recomendável que o código e a documentação de um projeto residam no mesmo repositório. (Uma boa maneira é tornar /doc ou /docs um diretório de nível superior no repositório.) Por um lado, isso torna a documentação fácil de ser encontrada por qualquer pessoa. Mais importante ainda, sua documentação estará em pé de igualdade com o código e outros recursos do projeto quando tudo estiver no mesmo repositório.

3. Faça da documentação um requisito para uma fusão ou marco de lançamento: Se o seu projeto tiver um ciclo de lançamento longo (por exemplo, três a seis meses ou mais), é altamente recomendável ter pontos de verificação provisórios para documentação (como este exemplo de comunidade ONAP). Isso garante que o trabalho de documentação não seja adiado até pouco antes do lançamento e, em vez disso, todos trabalhem na documentação durante todo o ciclo de lançamento. Se for viável para sua comunidade, você poderá tornar a documentação uma etapa obrigatória para todas as contribuições de código que impactarão os usuários (veja este exemplo do GitLab).

4. Ter um processo de contribuição consistente para código e documentação: Também recomendamos ter um processo de contribuição consistente e usar as mesmas cadeias de ferramentas para código e documentação. Como observamos anteriormente, muitos novos membros da comunidade começam a contribuir trabalhando na documentação, já que muitas vezes não é necessário conhecimento técnico profundo do software para começar. É bom que novos colaboradores se integrem à comunidade, familiarizando-se com o fluxo de trabalho de contribuição e conhecendo outros membros da comunidade. Se esses novos colaboradores quiserem se envolver posteriormente em outras partes do projeto (incluindo o código), você deseja que as cadeias de ferramentas e o processo de contribuição sejam familiares. Caso contrário, eles precisarão passar por outro processo de integração, o que cria um obstáculo desnecessário para os colaboradores. Se o seu código e documentação tiverem processos de contribuição diferentes, você corre o risco de criar a impressão de que a documentação é menos do que um cidadão de primeira classe em comparação com o código.

5. Ter processos bem documentados para contribuir com a documentação: Isso pode parecer óbvio, mas é fácil de negligenciar. Como a documentação é um bom ponto de entrada para novos contribuidores, você deseja diminuir a barreira de entrada tanto quanto possível. Ter uma boa documentação sobre o fluxo de trabalho de contribuição, como começar, onde encontrar problemas para trabalhar, como obter ajuda e muito mais ajudará muito a ajudar os novos contribuidores a se sentirem bem-vindos e a se envolverem em sua comunidade.

O que mais?

Você tem outras dicas para tornar a documentação um cidadão de primeira classe em comunidades de código aberto? Se sim, por favor, compartilhe-os nos comentários.

Este artigo é baseado no artigo Garantindo que a documentação seja um cidadão de primeira classe em projetos de código aberto apresentado no Open Source Summit North America em junho de 2020.