Como documentar na nuvem

Nunca houve uma boa desculpa para não comentar códigos ou documentar sistemas, apesar dessas práticas serem tão úteis para o controle de custo e para a qualidade dos sistemas quanto os testes.

Infelizmente, trabalhar em cloud computing pode dar aos desenvolvedores uma nova desculpa: “não tenho nenhum acesso ou controle sobre esse serviço (nuvem pública), então não posso documentar nada”.

Aham. Puro blefe.

Todos os consumidores de cloud (pública ou privada) precisam documentar o que o serviço faz, como é usado e seus comportamentos (incluindo bugs e erros reportados pelos usuários).

Um boa prática é inserir essas informações em um Wiki, no Google Docs, ou outro serviço colaborativo de livre acesso por toda a equipe de desenvolvimento e integração. Eles funcionarão como um repositório centralizado de conteúdos criados e mantidos por todos os membros da equipe de desenvolvimento – por mais distribuídos que eles possam estar, fisicamente.

De acordo com a minha experiência, a alternativa de ter uma equipe centralizada responsável pela criação e manutenção de diretórios de dados, modelos de relacionamentos, descrições de processos de negócios, ou documentação de interface produzem apenas duas coisas: uma desculpa para não fazer a documentação ou, na melhor das hipóteses, uma documentação obsoleta ou incorreta.

Um Wiki seria também um bom  lugar para comentar e documentar detalhes de uma variável? Não é uma má ideia, mas a maior parte do tempo os desenvolvedores simplesmente não estarão na área da documentação enquanto trabalham nos códigos. Nesses casos, comentários in-line devem ser encorajados e também mensurados. Seu sistema de integração de código pode já ter contadores e mecanismos apropriados para isso. Se não tiver, sempre é possível criar scripts para tal.

Em alguns aplicativos desenvolvidos para cloud há scripts, fluxos de trabalho e linguagens sem suporte nativo para comentários. Mas há uma forma de corrigir isso, por meio da inclusão de fragmentos de código inoperantes com as mensagens de documentação.

Em aplicativos mordenos, baseados em cloud computing, muito da ação não está no código: é programação declarativa e campos/objetos/relações personalizados. Nesse caso, documentar durante o desenvolvimento deve ser incentivado e medido.

Conclusão: mesmo que a nuvem não force qualquer documentação ou torne-a mais fácil de aplicar, existem maneiras mais inteligentes de usar os recursos do aplicativo em nuvem e os protocolos de serviço Web para tornar mais modernos os sistemas de auto-documentação. Aplique-as em seu próximo projeto de cloud.