Qual o papel da documentação de software quando uma metodologia ágil é aplicada em um projeto?

Oi Rodrigo, tem coisas que não necessariamente estão escritas nas funcionalidades que você vai entregar. Muitas vezes ninguém te diz que o software precisa estar cobertos por testes de unidade.. Mas vc faz isso pq preza pela qualidade do que vai ser entregue. A documentação, pelo menos para mim, vai entrar em um cenário parecido.

Pode ser que sua empresa descubra que o software bem documentado, independente do tipo de artefato(uml, javadoc etc) esteja ajudando muito na qualidade do software entregue. Isso vai virar peça de argumentação com o seu cliente, já que os pedaços não documentados podem estar gerando mais trabalho na manutenção.

Alberto, antes de mais nada, obrigado pela resposta. Obrigado por dedicar tempo. Isso é muito bacana da sua parte.

Sinceramente, acho que falta objetividade na sua resposta. Vou procurar esclarecer o motivo a seguir.

Quando eu perguntei: "Qual o papel da documentação de software dentro das metodologias ágeis?" O que eu espero é entender a contribuição dos documentos/artefatos para o projeto que faz uso de metodologias ágeis.

"Quando se fala no termo 'Documentação de software', quais os artefatos que esperamos ter?" - Aqui o que eu quero são exemplos de quais os artefatos mais utilizados e como/porquê esses artefatos contribuem com o projeto.

E por último, mas não menos importante: "Como é possível organizar essas documentações de software ao final de cada iteração?". Quero ter ideia de como as equipes ágeis organizam os documentos produzidos. Há exemplos de software que atuam como facilitadores desse procedimento, ou o trabalho é mais artesanal no sentido de que se usam ferramentas muito primitivas na documentação, como por exemplo Microsoft Word.

Se tiver dúvida sobre qualquer dos pontos, basta responder aqui. Ficarei feliz em poder esclarecer! Mais uma vez, obrigado pela resposta e tempo dedicado a estas questões.

Oi Rodrigo,

o Alberto me avisou da sua dúvida e vim ver se consigo ajudá-lo. :-)

Qual o papel da documentação de software dentro das metodologias ágeis? Quando se fala no termo 'Documentação de software', quais os artefatos que esperamos ter?

Dentro de métodos ágeis, preferimos software em funcionamento mais que documentação abrangente.

As razões para essa frase aparecer no Manifesto Ágil são várias, mas, para mim, a mais impactante é que, quando temos uma documentação extensa, frequentemente cria-se a ilusão de que não precisamos conversar com o cliente e entendê-lo melhor, já que o documento (supostamente) cobriria essa função. No entanto, esse pensamento se baseia em pontos perigosos: assume-se que quem escreveu a documentação realmente entendia do negócio, que essa pessoa (ou comitê) conseguiu escrever de forma clara para todos os indivíduos que a consumirão, que esses indivíduos vão interpretar o texto bem e ninguém esquecerá de detalhes potencialmente muito importantes... e de que esse documento será sempre atualizado, conforme as mudanças aconteçam.

Na prática, a frase do Manifesto significa que evitamos desperdiçar tempo com documentações que não serão lidas ou que ficarão obsoletas rapidamente. Em vez disso, preferimos que o próprio software seja sua documentação, através de:

1. Testes de unidade automatizados: código que verifica um método/função/classe que, para um dado cenário controlado, a saída esperada é tal. Essa é uma documentação para o desenvolvedor que for alterar esse código interno no futuro.

2. Testes de aceitação automatizados: código que simula o que o usuário do sistema fará, seu comportamento usando uma funcionalidade. Essa é uma documentação para quando o time for alterar o que um determinado código faz.

3. Clean code: prática de trabalhar ativamente para deixar o código claro e coeso, para que o próximo que venha a mexer nele não precise gastar tempo desvendando o que ele faz. Esse é um guarda-chuva gigante de boas práticas no dia-a-dia de desenvolvimento.

4. Se o código ainda não está bom, a ponto de qualquer um entendê-lo... Documentação dinamicamente gerada: geração automática, através de ferramentas específicas de cada linguagem, da relação entre as partes e classes do sistema. Frequentemente, usa-se UML aqui, e há diversas ferramentas que analisam um código e geram os diagramas que refletem o estado atual do design e arquitetura do sistema.

É claro que, dependendo do seu contexto, você pode ser obrigado a prover certas documentações para, por exemplo, o cliente. Nesse caso, fazemos o possível para evitar trabalho desnecessário, mas... infelizmente, jogamos com a regra do jogo atual.

Como é possível organizar essas documentações de software ao final de cada iteração?

O método mais comum para nos certificarmos que uma certa documentação obrigatória seja entregue é acrescentar um passo ao nosso Critério de Pronto, para que todo o time saiba, claramente, que todo item desenvolvido precisa ser documentado e, também, para que eventuais gargalos nesse step fiquem explícitos para todos.

Respondi suas dúvidas? Faltou algum ponto? :-) Só avisar!

[]s

Cecília e Alberto, muito obrigado pela resposta, muito obrigado também pelo tempo dedicado à resposta.

Cecília, dúvida absolutamente sanada! Sua resposta foi muito explicativa.

Muito obrigado!