Alguns pensamentos sobre “documentação ágil”

Existe um mito de que não se documenta em projetos que usam metodologias de desenvolvimento ágil. Não é bem assim, aliás, não chega nem perto de ser verdade.

A grande diferença entre projetos “tradicionais” e de desenvolvimento ágil é que os processos tradicionais geralmente são bastante prescritivos e você tem que documentar tudo que estiver definido no processo (que geralmente é muita coisa). Você não pensa no que está fazendo, simplesmente segue o que foi definido e escreve documentos. Em métodos ágeis não há prescrição de documentação (e o manifesto ágil fala também sobre “software funcionando mais do que documentação”), mas isso não significa que você não pode documentar nada. Muita gente confunde isso e diz que nunca se deve documentar em projetos “ágeis”, o que é um grande engano. Em projetos ágeis você pode documentar sem problemas desde que seja necessário de fato. A idéia é que você não deve perder tempo com nada que não seja requerido de verdade para o projeto.

Já participei de projetos onde documentar foi extremamente necessário. Por exemplo, uma vez trabalhei num projeto com vários times onde nem sempre os desenvolvedores estavam no mesmo espaço físico, portanto era preciso documentar alguns pontos chave da arquitetura e ambiente para que todos pudessem trabalhar sem problemas. Também já participei de situações onde meu time desenvolvia componentes que precisavam ser usados por outros times, e esses componentes precisavam estar bem documentados para que os outros times pudessem trabalhar adequadamente. Note que isso é totalmente diferente de documentar o projeto inteiro ou escrever dezenas de casos de uso. Documentamos apenas o que fazia sentido ser documentado.

Enfim, há diversas situações onde você pode precisar documentar por diversos motivos. Para te ajudar a decidir quando documentar e como documentar, veja a seguir alguns princípios do que chamei de “documentação ágil”. Essas são apenas algumas práticas úteis e princípios importantes que observei ao longo do tempo em diversos projetos de que participei. Certamente existe muito mais do que isso, mas vamos lá:

Documentação não substitui comunicação

Em projetos tradicionais, muitos documentos são usados para comunicar idéias entre o Analista e o Programador, com QA e por ai vai. Em desenvolvimento ágil o objetivo da documentação é registrar as informações por outros motivos (como os motivos acima). Se você estiver se comunicando por documentos, você já deixou de ser ágil há muito tempo. Documentação não deve ser usada para substituir a comunicação intensa e constante entre os membros do time.

Documentação não pode ser perecível

Documentação tem que ser leve e não pode ser perecível, ela deve ser durável. Se você documenta algo que precisa ser modificado todo dia, existem grandes chances de você esquecer de atualizar a documentação e ela passa a ficar desatualizada. É melhor não ter documentação do que ter documentação errada. Além disso, se você precisa mudar a documentação toda hora significa que você está se aprofundando demais nos detalhes, e então a documentação vai “quebrar” a cada linha de código que você escrever. Quando estiver documentando, pergunte-se: “daqui a algum tempo essa documentação ainda será válida?”. Faça documentação durável. Não entre num nível de detalhe que te faça mudar a documentação o tempo todo (a não ser que você realmente precise disso – e mesmo assim pense se não dá pra fazer de outro jeito, por exemplo, automaticamente).

Documente o necessário, e não mais do que isso

Assim como você deve implementar apenas o necessário para entregar uma funcionalidade e não mais do que isso, você deve documentar apenas o que for necessário e nada mais do que isso. Não perca tempo escrevendo documentação que nunca será usada por ninguém. Se ninguém precisa usar a documentação, então ninguém deve documentar. Documento tem que ter um motivo, documentar sem uma necessidade real não faz sentido

Documentar tem que ser fácil

Documentar tem que ser rápido, não pode dar trabalho. Use ferramentas como wikis, geradores de documentação (como o Sphinx) e por aí vai. Se for fácil documentar, as chances de você fazê-lo serão maiores. No caso de não usar wiki (ou alguma coisa online/web), use ferramentas para publicar a documentação automaticamente. Se a documentação for fácil de ser acessada (e tiver busca) ela fica mais útil. Além disso, prefira usar uma tecnologia fácil e conhecida para que todos os membros do time possam documentar. Por exemplo, se você escolher usar LaTeX, você está reduzindo as chances de designers documentarem, pessoas de negócio e outros membros não-programadores de um time.

Documentação faz parte do “Definition of Done”

Se o seu projeto precisa de documentação por qualquer motivo, a documentação deve fazer parte da “Definition of Done”. É melhor documentar no momento que as histórias estao sendo desenvolvidas – quando o conhecimento está fresco na cabeça – do que acumular um monte de débito e ter que pagar de uma vez só – quando você vai precisar conferir um monte de coisas que já estão prontas para documentar com precisão, o que vai te dar mais trabalho e consumir mais tempo.

Documentação no código pode ser um “code smell”

“Code smell” é um sintoma no seu código que pode indicar um problema maior. Muitas vezes códigos precisam ser documentados porque eles são desnecessariamente complexos. Sempre que possível prefira refatorar o código para ele ficar mais fácil de entender ao invés de escrever comentários (até porque muitas vezes o código muda e o comentário fica lá desatualizado, e isso acaba mais atrapalhando do que ajudando). Tenha uma boa suite de testes (uma suite bem escrita e organizada é uma especificação executável), use Domain-Driven Design para expressar melhor o domínio do software, metáforas, tenha um design simples, use design patterns, enfim, é melhor fazer com que o software seja mais bem escrito e não mais bem documentado.