Documentação em Processo Agil - Debate sobre matéria MJ 26

Assuntos Gerais Agile
#1

Srs,

Antes de mais nada gostaria de parabenizar o Rodrigo Yoshima pelos otimos arquivos que vem escrevendo na mundo Java, citando em especial as duas ultimas edições.

Mas diante da matéria, surge uma duvida:
Quais documentações tecnicas os agilistas consideram essenciais, quais são de escolha da equipe e quais são completamente despresiveis, tendo em vista que o cliente precisa de algum tipo de documentação?!?

Como fica o “tempo” de contrução desses artefatos? O melhor modelo é contruir a documentação só após ao marco de entrega (iteração)? Usa um Pair Programming para a contrução do artefato?!? Não existem artefatos?!?

Como fica a confirmação da comunicação com o cliente? Atas? Sabemos que o que o cliente disse hoje, mesmo sendo identico ao que vc construiu não é o que ele vai querer daqui até a ultima iteração.

Preciso comprar um livro sobre alguma metodologia agil em português para deixar na biblioteca da empresa para dominio da equipe. Alguma sugestão?!?

#2

… escrevi no tópico errado…

#3

Realmente, o Rodrigo tem feito um ótimo trabalho e está de parabéns, pois suas matérias estão cada vez melhores!

[quote=rodrigoallemand]Quais documentações tecnicas os agilistas consideram essenciais, quais são de escolha da equipe e quais são completamente despresiveis, tendo em vista que o cliente precisa de algum tipo de documentação?!?
[/quote]
rodrigoallemand, a equipe é quem define isto e depende das suas necessidades, pois a equipe é quem vai dizer: só consigo entregar o produto com qualidade (interna e externa) se produzir tais artefatos.

Eu e a equipe com a qual trabalho, geramos os seguintes artefatos: Use Case, Documento de Arquitetura e em alguns casos diagramas de seqüência, atividade e estado. Fazemos isto utilizando tWiki e javadoc. Vale ressaltar que tudo vai de acordo com a necessidade da equipe.

[quote=rodrigoallemand] Como fica o “tempo” de contrução desses artefatos? O melhor modelo é contruir a documentação só após ao marco de entrega (iteração)? Usa um Pair Programming para a contrução do artefato?!? Não existem artefatos?!?
[/quote]
O objetivo da iteração é entregar os itens priorizados e selecionados com o cliente com qualidade de produção. Portanto os documentos e artefatos são uma necessidade da equipe para conseguir atingir tal objetivo. Desta forma os artefatos são produzidos na dentro da iteração.

[quote=rodrigoallemand] Como fica a confirmação da comunicação com o cliente? Atas? Sabemos que o que o cliente disse hoje, mesmo sendo identico ao que vc construiu não é o que ele vai querer daqui até a ultima iteração.
[/quote]
Como sabemos e você mesmo disse: o cliente sempre vai mudar de idéia (o requisito vai evoluir).
A idéia de métodos ágeis é justamente antecipar ao máximo estas mudanças e incorporá-las ao produto.
Eu não registro esta comunicação em nenhum artefato específico (ata, por exemplo).
A idéia é ter o cliente próximo durante toda a iteração e não somente no início e fim da mesma!

Diariamente eu e a equipe temos contato com o cliente, quer seja para refinar o requisito, para validar o protótipo, para resolver dúvidas, etc e por este motivo não julgamos necessário registrar nossas conversas e decisões em nenhum tipo de artefato além daqueles que citei acima.

Segue a lista de referências que utilizamos:

Livros

Agile and Iterative Development: A Manager?s Guide by Craig Larman
Agile Estimating and Planning by Mike Cohn
Agile Project Management with Scrum by Ken Schwaber
Agile Retrospectives by Esther Derby and Diana Larsen
Agile Software Development Ecosystems by Jim Highsmith
Agile Software Development with Scrum by Ken Schwaber and Mike Beedle
Scrum and The Enterprise by Ken Schwaber
User Stories Applied for Agile Software Development by Mike Cohn

Sites e Artigos

http://www.scrumalliance.org
http://www.methodsandtools.com/


http://www.scrumalliance.org
http://www.controlchaos.com


http://www.softhouse.se/Uploades/Scrum_eng_webb.pdf
http://www.objectmentor.com/omTeam/devos_m.html
http://www.scrumalliance.org/
http://agilemanifesto.org/

http://www.agilebrasil.com.br/

#4

[quote=AvilaCS]Eu e a equipe com a qual trabalho, geramos os seguintes artefatos: Use Case, Documento de Arquitetura e em alguns casos diagramas de seqüência, atividade e estado. Fazemos isto utilizando tWiki e javadoc. Vale ressaltar que tudo vai de acordo com a necessidade da equipe.
[/quote]
Mas normalmente o cliente precisa de um documento que explique para uma manutenção futura o que eu contrui. Não necessariamente será a mesma emprea ou o mesmo prestador.
A minha pergunta era pra validar o modelo que estamos trabalhando hoje em um projeto (que é o primeiro que é balizado por uma metodologia agil): documentos só dos use cases que realmente tem uma tecnica especializada, excluindo-se os use cases dados como “padrão”, como CRUD de entidades, por exemplo.

Ai surge a duvida: se a iteração tambem defende o lado cliente (quando ele não achar favoravel o produto “sistema” o contrato pode ser cancelado) ele precisa dos artefatos descritos acima para garantir que a proxima empresa entenderá o que foi contruido, e que não jogue tudo fora.

Mas existem casos onde o cliente hoje fecha com vc umma determinada funcionalidade com urgencia máxima, ai vc prepara o prototipo, submete para aprovação e é aprovado. Inicia a contrução e no meio da iteração, o usuário fala que não é nada daquilo. Vc, para se resguardar, não deveria ter isso guardado em algum lugar?!?
Sei que as vezes eu trago o tradicionalismo para as metodologias ageis, mas infelizmente, com um mercado onde cada vez menos o cliente sabe o que ele quer e com os pagamentos trelados ao produto, faz-se necessario certos resguardos.

#5

Lembre-se: O cliente tem sempre razão!

#6

ha ha ha ha… :lol:

Infelizmente a area de tecnologia fez questão de destruir simples conceitos de marketing…

#7

Seus clientes tem sempre razão… os meus entram constantemente em “endoconflitos”… é comum eu sair de uma reunião pela manhã sobre o tema “A” e a tarde, outra pessoa me perguntar quando iremos incluir o “A” no sistema, ai eu passo a ata e ela diz que não tem nada a ver, que “A” não é assim e é assado… ai, vão mais 5 dias discutindo sobre o que é o “A” e como ficará o “A” no fim da história…

#8

Rodrigo, vamos por partes…

Os artefatos gerados durante o processo de desenvolvimento são para te ajudar. Você faz aqueles que são necessários. Infelizmente muito das suas dúvidas eu vou responder no artigo de Janeiro onde vou falar um pouco sobre artefatos.

Bom, as coisas tem que andar juntas, mas creio que 90% da minha documentação está no próprio código na forma de:

  1. Alta Coesão / Baixo Acoplamento / KISS*
  2. Padrões de Programação e Nomenclaturas
  3. Javadoc na medida certa
  4. Uso da tecnologia, frameworks para reduzir o número de classes
  5. MUITOS TESTES TDD
  6. Débitos Técnicos documentados usando //TODO:

Fora do código temos:

  1. Um Domain Model em UML (um artefato simples de manter fazendo reversas)
  2. Possivelmente alguns Casos de Uso / Espec Complementar
  3. Documento de Arquitetura

Quando você trabalha com Domain Modeling (seja em UML para capturar requisitos ou em código para programar) o código é recheado de conceitos de negócio de forma que fica bem simples a manutenção. Se o cara conhecer o negócio ele saberá manter o código. O código é a melhor documentação para isso.

Fiz algumas pesquisas informais para ver se documentações garantem a manutenabilidade do software e para minha surpresa, OS CARAS QUE MANTINHAM O CÓDIGO não usavam a documentação existente. O que eles usavam era:

  1. Conhecimento do cliente
  2. Os próprios conhecimentos
  3. O código (lógico)

Para esses caras, eles tinham tanta incerteza se a documentação estava atualizada que valeria mais a pena interpretar o código. Fui um pouco mais a fundo e perguntei o que tornava o trabalho deles mais difícil:

  1. Arquiteturas ruins ou a falta de uma arquitetura definida
  2. Procedures de 2000 linhas
  3. FALTA DE DOCUMENTAÇÃO NO CÓDIGO (veja a história do Zahl que o Shoes sempre conta)

É uma ilusão achar que artefatos de análise e design vão salvar a manutenção. E outra, não use artefatos para se comunicar dentro da equipe.

KISS - Keep it simple stupid.*

#9

Seus clientes tem sempre razão… os meus entram constantemente em “endoconflitos”… é comum eu sair de uma reunião pela manhã sobre o tema “A” e a tarde, outra pessoa me perguntar quando iremos incluir o “A” no sistema, ai eu passo a ata e ela diz que não tem nada a ver, que “A” não é assim e é assado… ai, vão mais 5 dias discutindo sobre o que é o “A” e como ficará o “A” no fim da história…[/quote]

Eleja um Product Owner dentro do cliente!

#10

Seus clientes tem sempre razão… os meus entram constantemente em “endoconflitos”… é comum eu sair de uma reunião pela manhã sobre o tema “A” e a tarde, outra pessoa me perguntar quando iremos incluir o “A” no sistema, ai eu passo a ata e ela diz que não tem nada a ver, que “A” não é assim e é assado… ai, vão mais 5 dias discutindo sobre o que é o “A” e como ficará o “A” no fim da história…[/quote]

Eleja um Product Owner dentro do cliente![/quote]

Rodrigoy, ótimos comentários. Principalmente:

  1. faça testes
  2. eleja um product owner

Vou acrescentar um último:

desenhe os casos de uso (mesmo que seja à mão). Mostre para o cliente no início o que ele vai ver no final. Textos são sujeitos a interpretação. Telas e relatórios são menos sujeitos a interpretação. E tiram mais rápido a dúvida do que foi pensado. Essa é a melhor ata. Lógico que isso não diz em que classe está cada coisa, mas é muito bom.

Outra coisa, a pressa da definição prejudica muito o projeto (a demora também).

#11

Em suas pesquisas, vc verificou se isso funciona bem quando o código, a equipe e o cliente estão dentro da mesma empresa ou tambem casos de fabricas remotas…
Digo isso pois muitos clientes grandes contratam 2 ou 3 fabricas para o mesmo projeto (não me pergunte o porque, eu tb acho uma burrice)… neste caso, sempre uma das fábricas é cortada e as outras vão absorvendo os códigos.
A minha ideia é gerenciar isso usando as metodologias ageis… depois do seu artigo, muitas coisas foram iluminadas… espero o de Janeiro!!!

#12

Na minha pesquisa levei em consideração CODIGO EM MANUTENÇÃO COM O SISTEMA EM PRODUÇÃO, não interessando quem fez o código. Não é uma pesquisa abrangente, mas acho que entrevistei umas 20-30 pessoas.

Bom, 2 ou 3 fábricas num mesmo projeto é algo muito ruim. (bem, 1 fábrica já é ruim, he he he, tô zuando). Nesse cenário as empresas teriam que ter uma colaboração muito boa. Daria para usar “Scalling SCRUM”, mas as empresas deveriam FAZER O MESMO. Isto é, o documento de arquitetura deveria ser um e deveria ser respeitado. O Domain Model também deveria ser único. O Product Backlog também. Você deveria buscar um Collective Ownership para que fique tudo coeso. TDD ajudaria bastante. TDD também documenta o código (assim como um documento de requisitos).

Será uma proeza, mas se tiver sucesso seria digno de você escrever um artigo sobre o caso.

#13

Vamos ver… vou colocando os pontos quando as duvidas surgirem!!
Mas valeu e parabéns pelos artigos!

#14

Ele precisa de software funcionando (em alguns casos ele nem precisa de software!! Mas isto é um outro papo! hehehe).

Vamos imaginar que você tenha que dar manutenção ou continuidade em um projeto. O que gostaria de ter em mãos para fazê-lo?

Eu gostaria de ter um documento de arquitertura (que defina camadas, pacotes, convenções, padrões, etc), uma breve descrição funcional do sistema e o código fonte (documentado com informações relevantes - não vou documentar um atributo nome ou um serviço somar, por exemplo).

Afinal de contas o que olhamos para dar manutenção ou evoluir um software? O código fonte ou um monte de documentos?

Por mais incrível que pareça isto é natural e normal! Então se no meio da iteração ele te dizer isto, você lhe dá duas opções:

1- Abortar a iteração e recomeçar com o novo escopo;

2- Finalizar a iteração e depois evoluir o que foi implementado para atender ao novo escopo;

A decisão é do cliente! Ele é quem definirá o que é mais importante!

#15

E ferramentas para suporte disso, algum sistema minha onde são cadastrados os backlogs ou coisas do tipo, existe?

#16

rodrigoallemand utilizamos ferramentas bem avançadas (hehehehe): cartolina, canetão e post-it.

Criamos também uma planilha simples para controlar o backlog

#17

Perfeito!!! A tecnologia que eu precisava!!!

#18