O que fazer e o que não fazer com a documentação ágil

Como as equipes passaram da Metodologia Cascata para formas ágeis de trabalho nas últimas duas décadas, formou-se um estigma negativo em torno da documentação. 

Muitas equipes interpretaram erroneamente a declaração do Manifesto ágil de "software de trabalho em detrimento da documentação extensiva" como "nada de documentação". Embora seja verdade que as abordagens tradicionais de documentação são ineficientes, eliminar a documentação completamente pode ser prejudicial para as equipes ágeis, principalmente à medida que o trabalho remoto e híbrido se torna mais comum. 

Imagine a construção de uma casa. Não importa o quão rápido, progressivo e eficiente você é: se você não fizer seu trabalho de amarração e fundação, a casa não ficará de pé por muito tempo. Da mesma forma, a documentação fornece às equipes ágeis a base necessária para aprender, adaptar, inovar e entregar valor aos clientes. Sem ela, as equipes ágeis ficam desalinhadas, propensas a erros e má comunicação, ineficientes, e não têm o contexto necessário para tomar decisões e se adaptarem às mudanças do mercado. 

Em outras palavras, embora a eliminação da documentação possa parecer uma maneira de aumentar a agilidade temporariamente, ela na verdade diminui significativamente a agilidade no longo prazo.

Em vez de se livrar completamente da documentação, as equipes se deparam com a oportunidade de fazer uma melhor documentação. A solução não é voltar à forma como a documentação era abordada nos tempos do Método Cascata; as equipes precisam adotar uma documentação orgânica, viva, adaptável e altamente visual.

Como é uma abordagem ágil para a documentação?

Uma abordagem ágil para a documentação segue muitos dos mesmos princípios do próprio Manifesto Ágil. Ou seja, ela deve ser iterativa, adaptável e colaborativa. O objetivo da documentação ágil eficaz deve ser:

• Compartilhar melhor o contexto entre equipes híbridas e eliminar idas e vindas desnecessárias
• Viabilizar uma entada no mercado mais rápida, seguindo modelos para processos reproduzíveis
• Criar uma experiência de integração eficiente para novos contratados

Dada a crescente complexidade dos negócios - mais software, mais dados, um ritmo acelerado de mudança e a crescente adoção de trabalho distribuído - as organizações não podem renunciar à documentação; é uma necessidade trabalhar de forma eficiente e inovar continuamente.

E como as empresas enfrentam orçamentos apertados, rotatividade de funcionários e outras ameaças a seus negócios, uma melhor documentação ajuda a evitar que o conhecimento valioso escorra pelos ralos de seu negócio.

Quais são alguns exemplos de documentação ágil? 

Documentação ágil envolve documentos, diagramas ou modelos que são simples de entender, altamente visuais e ajudam as equipes a tomar decisões e avançar. Alguns exemplos são:

• Backlog de produtos
• Gráficos de burn up e burndown
• Mapa de histórias de usuários
• Diagramas UML

Embora estes sejam documentos importantes para manter as equipes alinhadas, há também formas menos formais de documentar informações que são da mesma forma importantes para a inovação contínua.

Por exemplo, se você hospedar seus eventos ágeis remotamente, use uma sala de equipe virtual para capturar ideias, obstáculos ou feedback. Esse espaço virtual funciona como uma forma de documentação viva que oferece um registro do contexto e das decisões do projeto.

O que fazer e não fazer com a documentação Ágil

Com tudo isso em mente, aqui estão algumas dicas táticas para abordar sua prática de documentação ágil:

Fazer: documentar continuamente enquanto você trabalha

Grande parte da reclamação sobre a documentação é que é um processo intensivo que tira muito tempo do trabalho real de codificação e desenvolvimento de produtos. Não precisa ser assim, no entanto.

Um artigo recente da InfoQ postula uma abordagem à documentação contínua que prega o acoplamento de sua documentação ao seu código e a produção de documentação "quando for melhor" — o que pode ser imediatamente após uma correção de bugs, por exemplo, em vez de apenas após um grande projeto. E os próprios artigos da Lucid sobre repositórios de inovação sugerem uma abordagem de transformar todo o trabalho de brainstorming, planejamento e execução mais amplo que você já está fazendo em um "esquema vivo" de como sua empresa dá vida às suas melhores ideias.

Pensar na documentação dessa forma torna-a uma extensão natural da criação, da codificação, da segurança, das vendas de testes e do processo de marketing — não uma tarefa separada que você faz de forma relutante. Também é mais eficiente documentar enquanto você trabalha porque você é capaz de fazer notas de processo enquanto as ideias ainda estão frescas na mente.

Não fazer: criar documentação apenas com o propósito de documentar

Durante todo o processo de documentação contínua, é importante fazer as seguintes perguntas para evitar criar documentação só por criar:

• Qual é a finalidade desta documentação?
• Para quem é este documento e como essa pessoa o usará? 
• Este documento já existe em outro lugar?

Adotar uma mentalidade de documentação contínua não significa que você precisa fazer um trabalho redundante; em vez disso, você deve procurar oportunidades para adicionar e melhorar a documentação existente sempre que possível.

Abordar problemas de versão, otimizar uma documentação difícil de encontrar ou difícil de ler para facilitar a descoberta e a legibilidade, ou adicionar capturas de tela e diagramas para ilustrar uma documentação com textos densos são maneiras importantes de impactar a base de conhecimento da sua empresa além de apenas criar novos documentos do zero.

Fazer: procurar oportunidades para automatizar quando possível

Adicionar banco de dados e outras integrações pode reduzir erros que surgem quando você precisa atualizar a documentação manualmente, especialmente para diagramas de entidade relacionamento (DER) ou outra documentação que mostre relacionamentos de dados complexos. 

A automação também pode ajudar você a economizar tempo e trabalho manual, atualizando partes importantes da sua documentação sem que você sequer pense sobre isso (ou saiba que está acontecendo). Ter os dados mais novos na ponta dos dedos em vez de ter que ir atrás deles pode ajudar você a gerar melhores insights acionáveis e descobrir padrões que você de outra forma poderia ter deixado passar.

Não fazer: esperar até o final do seu projeto para então documentar

Esperar até que um projeto termine para documentar traz o risco de esquecer informações, introduz mais espaço para erros e adiciona um fardo desnecessário no final de um longo sprint quando o entusiasmo para fazer "mais uma coisa" provavelmente será o mais baixo.

Ao abordar a documentação ágil na perspectiva de construir um repositório de inovação no momento e ao longo do tempo, a documentação fica incorporada como parte natural do projeto —desde a geração de ideias e o planejamento até o design e o lançamento— em vez de uma tarefa abordada no final.

Não fazer: produzir documentos em silo

É ineficiente gastar tempo criando documentos individualmente e, em seguida, coletar feedback somente quando você está apenas com um rascunho. Se o escopo de sua documentação estiver desativado, ou detalhes críticos estiverem faltando, agora você terá que gastar bastante tempo refazendo algo que era completamente evitável.

Envolver outras pessoas no início através de entrevistas de descoberta para saber qual documentação é realmente necessária — ou colaborar na documentação em si — poupará tempo e sofrimento lá na frente.

Fazer: criar documentação de forma colaborativa com a equipe

A documentação não precisa ser um esforço individual, especialmente quando você está criando sua documentação a partir de código, quadros de brainstorming, mapas de planejamento ou outros documentos que vocês já criaram juntos como uma equipe.

Envolver outras pessoas no processo garante sua conscientização e adesão, tornando-o um processo colaborativo. Também cria uma responsabilidade coletiva para garantir que sua organização seja rigorosa em relação à documentação, o que reforça a importância de manter os documentos atualizados em equipe. Para funcionários mais novos ou juniores, estar envolvido no processo de criação também pode ser uma experiência de aprendizado consistente.

Um dos maiores problemas com a documentação é a frequência com que ela precisa ser atualizada e quanto trabalho de comunicação e distribuição precisa acontecer para garantir que todos estejam cientes de que uma nova versão está disponível.

Usar uma opção de armazenamento na nuvem — de preferência uma que acomoda a colaboração visual para tornar as informações ainda mais compreensíveis — significa que você não precisa lidar com problemas de versões desatualizadas e garante que os membros da equipe tenham acesso às informações necessárias para tomar decisões de forma rápida e segura.

Não fazer: usar a documentação para substituir a conversa

Embora a documentação visual clara possa permitir um trabalho assíncrono, ela deve complementar a conversa, não substituí-la. Criar uma documentação melhor não quer dizer deixar de lado a necessidade de colaborar com os colegas de equipe — isso deveria, no entanto, tornar essas conexões mais fortes e informar conversas que levem a um pensamento de vanguarda e à inovação.

Lembre-se deste princípio ágil: o método mais eficiente e eficaz de transmitir informações para e dentro de uma equipe de desenvolvimento é uma conversa presencial.

Fazer: usar elementos visuais simples e envolventes

Documentação que prioriza visuais em relação ao texto puro ajuda a esclarecer informações complexas, mostrar relações entre entidades mais claras e é mais facilmente digerível de uma só vez para as partes interessadas.

Imagine entrar em uma nova empresa e descobrir que o organograma deles é escrito inteiramente como uma lista enumerada por pontos. Não há hierarquia ou níveis ou linhas mostrando estruturas de relatórios, apenas uma lista de nomes e cargos — e todo o trabalho pesado de entender a relação entre diferentes indivíduos e equipes fica para você.

Embora um exemplo extremo, o mesmo princípio se aplica ao uso de recursos visuais para qualquer tipo de documentação. Recursos visuais claros evitam que o leitor tenha que gastar energia para entender estruturas complexas, relacionamentos e dependências, liberando o tempo do profissional para se concentrar em responsabilidades reais no trabalho.

Não fazer: criar documentos excessivamente densos e com muito texto

Na tentativa de ser minucioso com a documentação e colocar tudo que está na sua cabeça no papel, pode ser difícil lembrar que você não está necessariamente escrevendo a documentação para si mesmo. Se você está escrevendo para você mesmo, e não para os outros, você pode tender a dar uma olhadinha não atenciosa aos passos importantes, deixar passar batido faltas de informação importantes ou relevar informações importantes em uma densa muralha de texto.

O problema com isso é que muitas vezes você fica com um documento que pode fazer sentido para você — porque você tem experiência e contexto sobre o processo — mas é inacessível para alguém que tenta executar o processo pela primeira vez.

Se você achar que a documentação está regularmente levando muito tempo para ser produzida, pode ser que você esteja sendo muito prolixo. Se a documentação é tão densa que não está clara e não pode ser usada, não é uma boa documentação. Quanto mais simples, melhor.