Raphael Amoedo
Jun 4 · 4 min read
Fonte: https://www.digiscribe.info/blog/paperless-budget-planning/

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.

Exemplo de documentação gerada através de testes. Fonte: https://github.com/rmpestano/cukedoctor

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.

Exemplo de documentação de schema de database: http://schemaspy.org/sample/index.html

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.

Labs OLX Brasil

O OLX Labs nasceu para compartilharmos o conhecimento adquirido no dia a dia da OLX Brasil com a comunidade. Falaremos sobre resultados de projetos, metodologias de trabalho, processos, nossa cultura e valores e todo tipo de conteúdo relevante para o ecossistema de Tecnologia.

Raphael Amoedo

Written by

a.k.a. Ralph Avalon — https://github.com/ralphavalon — Developer at OLX — Passions: Best programming practices, Clean Code, Java, Python, DevOps, Docker, etc.

Labs OLX Brasil

O OLX Labs nasceu para compartilharmos o conhecimento adquirido no dia a dia da OLX Brasil com a comunidade. Falaremos sobre resultados de projetos, metodologias de trabalho, processos, nossa cultura e valores e todo tipo de conteúdo relevante para o ecossistema de Tecnologia.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade