Precisamos falar sobre Documentação (Parte 1)
Como manter a documentação sempre atualizada? Existe alguma forma de automatizar documentação? Que tipo de informação dá para colocar que seja relevante e esteja atualizada? Existem técnicas para isso?
“A melhor forma de manter a documentação atualizada é não mexer na documentação.” — Já dizia o sábio (mentira, ninguém disse isso, pelo menos eu acho que não — se ninguém disse, então a citação é minha =P).
Essa frase está associada ao fato de que é possível obter uma documentação atualizada sem que você se preocupe com escrevê-la. Mas, claro, às vezes é necessário acrescentar uma coisa ou outra, afinal, é impossível possuir uma riqueza de detalhes de forma automática. Como manter a documentação atualizada com o menor esforço possível?
O foco desse post é apresentar principalmente os conceitos, a teoria e técnicas para ajudar e facilitar a atualização da documentação. Eu vou dividir aqui em 3 partes principais: Automatizada, Semi-Automatizada e Manual.
Documentação Automatizada
Chamo aqui de automatizada porque a ideia é não precisar escrever documentação.
Living Documentation
Living Documentation é um conceito comumente associado ao BDD (Behavior-Driven Development — Desenvolvimento Guiado por Comportamento) — mas não necessariamente é só BDD. Há tempos atrás fiz alguns posts comentando sobre BDD (parte 1 e parte 2) e sua ajuda na legibilidade e manutenibilidade do código.
Mas então, como manter uma documentação atualizada sem mexer na documentação? Com os testes. O conceito de Living Documentation vem com base de que a documentação pode ser gerada através dos testes, que são coisas que têm que ser feitas.
Uma vez que passamos a entender que os testes podem ser utilizados para documentação, abrem-se muitos caminhos e muitas opções. Ainda com relação aos posts anteriores, vimos que um dos benefícios do BDD é a possibilidade de testes serem escritos por pessoas que não são desenvolvedoras. Acrescentando isso no conceito de Living Documentation, qualquer pessoa poderia contribuir com a documentação, afinal, qualquer tarefa deve possuir testes, então teoricamente você não estaria escrevendo documentação, e sim testes que virariam documentação.
Documentação como pipeline
Ainda citando testes como documentação, existem algumas outras coisas que podem ser documentadas utilizando apenas o pipeline do seu build. Coisas como schema de databases ou testes específicos (como de carga, por exemplo). No exemplo abaixo, de schema de database, nem seria necessário criar testes para isso, bastaria apenas acesso para ler um banco de dados (mesmo que local de desenvolvimento) para interpretar a estrutura e gerar a informação. Atrelando isso a um pipeline, qualquer alteração no banco de dados já atualizaria automaticamente a documentação.
Documentação Semi-Automatizada
Chamo aqui de semi-automatizada porque em algum momento é necessário escrever a documentação mas parte é ou pode ser automatizada.
Documentação no código
Nesse modo, o código pode ficar um pouco poluído agregando detalhes de documentação, mas no geral, o trabalho "sujo" fica para alguma ferramenta que entende esses detalhes e transforma em uma documentação bonitinha.
Nesse modo, normalmente encontram-se documentações mais técnicas, como de API ou coisas relacionadas ao código. Normalmente esse modo também inclui uma parte de conversão do que foi escrito no código para um formato específico e/ou para a visualização (como visto acima).
Documentação Manual
Esse é o método tradicional. Aquele que não tem jeito: você vai lá ter que escrever a documentação independente de testes, código e etc. Sendo assim, uma possível solução/recomendação seria essa:
Documentação como definição de pronto
Existem muitas divergências sobre definição de pronto. Uns acreditam ser quando a tarefa é terminada, outros acreditam ser quando a tarefa está em produção e por aí vai. A ideia aqui é ajudar a colocar a documentação como um processo da definição de pronto, então se para você, pronto é quando a tarefa é terminada, se tornaria então tarefa terminada e documentada.
Se você quer/tem que seguir esse caminho, a sugestão é escolher alguma ferramenta que facilite bastante o trabalho.
Conclusão
Independente da forma escolhida, todas têm algo em comum: o uso de ferramentas para otimização da documentação. Sabemos que no mundo de tecnologia, falar de ferramentas é sempre complicado porque tudo muda o tempo todo, mas se elas estão aí, valem a pena serem mencionadas. Na continuação do post, vou citar algumas dessas ferramentas para facilitar esse trabalho.
Aqui ficaram algumas dicas das formas de documentação, mas obviamente não são as únicas. Caso eu tenha esquecido alguma ou conheçam alguma diferente, podem colocar nos comentários.
