A documentação técnica sempre foi um ponto de tensão no mundo do desenvolvimento de software. Equipes DevOps muitas vezes nutrem uma relação de amor e ódio com ela: amada pela sua importância teórica, mas frequentemente negligenciada na prática. Desenvolvedores, conhecidos por sua paixão por código, muitas vezes detestam a ideia de documentar ou manter códigos não documentados. Diagramas de arquitetura, embora visuais, podem se distanciar da realidade implementada. Até mesmo os fluxos de processos de ITSM (gerenciamento de serviços de TI) para incidentes, requisições e gerenciamento de mudanças raramente seguem o que foi especificado na documentação.
Apesar da insistência de CIOs, CTOs e outros líderes digitais na importância da documentação, os orçamentos de projetos raramente incluem redatores técnicos. Em equipes ágeis, o tempo é um bem escasso, limitando a documentação ao nível do código, arquivos README e outros elementos básicos. Embora os donos de produtos capturem requisitos em histórias de usuários ágeis, a documentação que orienta as regras de negócios, mapas de jornada, arquitetura, APIs e procedimentos operacionais padrão de um aplicativo raramente é completa e atualizada.
O Potencial da IA Generativa na Documentação
A grande questão que se coloca é: como desenvolvedores, engenheiros e arquitetos podem usar ferramentas de IA generativa (GenAI) para escrever e manter documentação precisa? A resposta pode estar em transformar a documentação de um material de referência estático para uma camada dinâmica dentro da experiência do produto. Ao capturar fluxos de usuários e gerar orientação contextual automaticamente, a documentação pode evoluir em tempo real junto com o software, reduzindo atritos e melhorando a eficiência do usuário.
Alguns especialistas vislumbram um futuro onde a documentação tradicional se torna obsoleta, substituída por conhecimento gerado por IA sob demanda. Modelos de linguagem grandes (LLMs) poderiam alcançar um nível onde a documentação é verdadeiramente dinâmica, gerada instantaneamente em resposta a perguntas, chats ou prompts, extraída do conhecimento do modelo sobre a base de código, padrões da indústria, documentação existente e até mesmo tickets de suporte e logs do sistema.
Como a GenAI Pode Acelerar a Documentação em DevOps e ITSM
Independentemente do futuro, a GenAI já está tornando possível para equipes DevOps atenderem aos requisitos de documentação de forma mais eficiente. Além disso, há novos motivos para investir em documentação, à medida que as equipes DevOps utilizam agentes de IA e outras ferramentas de desenvolvimento de GenAI. Vamos entender como a documentação pode auxiliar:
- Integração de novos desenvolvedores: A documentação deve abranger a arquitetura, os requisitos não negociáveis de DevOps, o processo de desenvolvimento de software e a estrutura de código de alto nível para que novos membros da equipe se tornem produtivos rapidamente;
- Equipes de desenvolvimento externas: É importante revisar a documentação da API, arquivos README em repositórios Git, definições de dados em catálogos de dados e guias sobre arquivos de log e outros artefatos de observabilidade;
- Arquitetos, especialistas em segurança e engenheiros de confiabilidade de sites (SREs): A documentação é crucial para recomendar modernizações de aplicativos e programas para resolver dívidas técnicas, auxiliar na resposta a incidentes e realizar análises de causa raiz;
- Cientistas de dados, especialistas em governança de dados e engenheiros que trabalham em pipelines de dados: Eles precisam de acesso ao catálogo de dados atualizado e entender a linhagem dos dados, que usarão para a tomada de decisões orientada por dados;
- Gerentes de produtos, donos de produtos, líderes de mudança e outros especialistas no assunto (SMEs): Eles precisam de informações detalhadas sobre como o sistema funciona, indo além do que é fornecido nas notas de lançamento;
- Auditores para ISO 27001, ISO 9001, SSDF, CMMI, SOC 2 e outros padrões de conformidade: Eles precisam revisar a documentação exigida para garantir a conformidade;
- Assistentes de codificação GenAI e agentes de IA: A documentação é fundamental para melhorar a relevância e a precisão desses assistentes.
Estratégias Práticas para Implementar a GenAI na Documentação
Para documentar como os recursos funcionam, considere escrever e manter o seguinte:
- Uma especificação de recurso documentando os requisitos, incluindo a documentação do usuário final;
- Um projeto técnico curto que inclua seções de arquitetura, dependências, teste, segurança, configuração e implantação;
- Referências, incluindo links para histórias de usuários ágeis e tíquetes de gerenciamento de serviços de TI.
Algumas ferramentas para documentação de nível funcional incluem Microsoft Teams, Atlassian Confluence, Google Workspace, Notion e MediaWiki.
Documentação de APIs, Dicionários de Dados e Pipelines de Dados
Para documentar APIs, dicionários de dados e pipelines de dados, lembre-se de que as equipes de DevOps não são o público-alvo da documentação técnica. Os desenvolvedores que ingressam no programa ou assumem o controle de onde a equipe de desenvolvimento original parou são o público principal, juntamente com quaisquer desenvolvedores externos que utilizem APIs ou outros recursos externalizados.
Diferentes tipos de documentação técnica aproveitam diferentes ferramentas:
- O melhor lugar para documentar dicionários de dados é em catálogos de dados como Alation, Atlan, Ataccama, AWS Glue Data Catalog, Azure Data Catalog, Collibra, Data.world, Erwin Data Catalog, Google Dataplex Universal Catalog, Informatica Enterprise Data Catalog e Secoda;
- As equipes de DataOps que usam pipelines de dados, plataformas de integração de dados ou outras plataformas de integração podem usar ferramentas de design visual para fornecer diagramas de fluxo de dados e linhagem;
- As ferramentas para documentar APIs incluem Postman, Redocly, Swagger e Stoplight.
Documentação de Tempo de Execução e Procedimentos Operacionais Padrão
As práticas recomendadas de DevOps se concentram no fluxo de trabalho, ferramentas e configuração, deixando para as equipes decidirem como documentar as transferências de desenvolvimento para funções operacionais. Os seguintes tipos de ferramentas podem ajudar a preencher as lacunas:
- Ferramentas para criar bases de conhecimento operacional e procedimentos operacionais padrão: Atlassian Jira Service Manager, Freshservice Knowledge Base, ServiceNow Knowledge Management e Zendesk Guide;
- Ferramentas de análise de arquivos de log com IA: Datadog, Dynatrace, LogicMonitor, Logz.io, New Relic, Splunk e Sumo Logic;
- Ferramentas para visualizar a infraestrutura de nuvem pública: Cloudcraft, Hava e Lucidscale;
- Ferramentas para diagramar a arquitetura, sequências e outros fluxos: Draw.io, Figma, Eraser, Lucidchart, Miro e Visio.
Documentação para Agentes de IA: Contexto e Precisão Aprimorados
Embora muitos agentes de IA geradores de código analisem a base de código, um número crescente deles também pode analisar a documentação do software para obter contexto adicional. As equipes DevOps devem considerar fornecer aos geradores de código de IA documentação sobre APIs, histórias de usuários com critérios de aceitação, padrões de codificação, princípios de arquitetura, arquivos README, diretrizes de codificação segura, regras de privacidade de dados e referências de conformidade.
Modelos de linguagem grandes funcionam três vezes melhor com documentação detalhada porque podem entender o contexto, as restrições e as intenções. As equipes que usam essa abordagem relatam que, após seis meses, seus agentes de IA se tornam muito mais eficazes em entender seus padrões e convenções de base de código específicos.
O Desafio da Documentação de Sistemas Legados
A GenAI apresenta novas oportunidades para documentar aplicações legadas, especialmente aquelas cujos desenvolvedores originais não estão mais presentes na organização. A IA pode analisar o código fonte existente e resumir a intenção. Ela também pode ler configurações e documentá-las, além de analisar dados para determinar os processos reais usados.
Conclusão: A Documentação Certa na Medida Certa
Embora sistemas não documentados sejam problemáticos e possam ser um problema de conformidade, criar documentação excessivamente detalhada também é um desafio. A documentação de formato longo é difícil para os humanos consumirem e cara de manter, mesmo com a ajuda da IA generativa. A melhor abordagem é manter seu público em mente e manter apenas documentação suficiente. Toda a documentação deve ser direcionada para as pessoas que a revisarão e para os LLMs que a usarão para responder às suas perguntas.
Em um cenário de transformação digital acelerada, a IA Generativa surge como uma ferramenta poderosa para revolucionar a forma como abordamos a documentação técnica. Ao automatizar tarefas, gerar conteúdo sob demanda e garantir a atualização contínua da informação, a GenAI pode ajudar as equipes DevOps a superar a aversão à documentação, melhorar a qualidade do software e garantir uma experiência do usuário mais fluida e eficiente.