BT
x A sua opinião é importante! Por favor preencha a pesquisa do InfoQ sobre os seus hábitos de leitura!

Documentação na agilidade: quanto e quando escrevê-la?

por Ben Linders , traduzido por Bernardo Rosmaninho em 14 Fev 2014 |

Os valores do manifesto para o desenvolvimento ágil de software "software em funcionamento mais de documentação abrangente". Esse valor primário da agilidade nos questiona sobre "quanto" e "quais" tipos de documentos são necessários e "quando" eles devem ser escritos.

No post Entregando o Mínimo Possível (Minimum Viable Deliverable), Jonathan Berger escreve sobre a comunicação de suas decisões de design e compartilha sua visão sobre o uso da documentação:

O manifesto ágil prioriza "software em funcionamento ao invés de documentação abrangente", então porquê os designers investem tempo em artefatos que o usuário nunca vai ver? A agilidade busca minimizar o desperdício, então levando isso ao "pé da letra", toda documentação é um desperdício. Isso não significa que a documentação pode (ou deve) ser abolida inteiramente, é necessária para que as equipes funcionem (particularmente em escala). Por outro lado sugere que minimizar a documentação é uma boa coisa, e que os designers busquem comunicar suas decisões com o mínimo de trabalho possível.

Jonathan Berger sugere como podemos minimizar a documentação:

  1. Socializar a ideia que "menos artefatos pode ser melhor" dentro da sua equipe.
  2. Sempre fazer a pergunta: qual é mínimo de produto que precisamos agora?

Ashish Sharma escreveu sobre o equilíbrio entre a documentação e discussão na agilidade no artigo intitulado documentação essencial, valiosa e oportuna:

O objetivo da agilidade deve ser buscar o equilíbrio certo entre documentação e discussão. A documentação é uma parte importante de todo sistema, ágil ou não, mas por outro lado, uma documentação abrangente não garante o sucesso do projeto. Na verdade, aumenta suas chances de fracasso.

Ashish Sharma mencionou três critérios que podem ser usados para decidir quanto de documentação deve ser escrita e quando deve ser escrita:

Essencial: Documentar com detalhes suficientes.

Valiosa: Documentar somente quando for necessário, não quando quiser.

Oportuna: Documentação feita em tempo de desenvolvimento, quando necessário.

Michael Nygard descreveu uma visão de processo para a documentação sugerindo começar com o fim em mente:

Costumo encontrar processos que não eram utilizados. Pura perda de tempo! Literalmente ninguém usava a documentação, mas o responsável não percebia isso.

Processos, incluindo suas entradas e saídas, poderiam ser descritos da perspectiva do utilizador. Michael Nygard sugere uma série de questões para auxiliar nesse momento:

  1. Quem vai utilizar o documento?
  2. O que precisa ser documentado?
  3. Como a documentação será entregue?
  4. Como saber se a documentação pode ser entregue?
  5. Como a documentação será produzida?
  6. Quais são as entradas necessárias para produzir a documentação?

Tom de Lancey iniciou um debate em 2013 no LinkedIn sobre documentação emergente: um caminho no qual a agilidade difere bastante do método cascata:

Muitas pessoas estão muito desconfortáveis em deixar a conhecida forma de documentar que costumava ser: requisitos do sistema, design do sistema, visão e escopo, casos de uso, esquemas, diagramas de fluxo de trabalho, artefatos do RUP, entre outros. Muitos não conseguem conceber toda essa documentação em cinco frases de uma história.

Tom de Lancey descreveu uma abordagem de documentação chamada "documentação emergente":

(...) não queremos perder tempo e esforço em documentar alguma coisa que ainda não descobrimos como fazer. Documentamos na medida que descobrimos. Somente documentamos o que realmente FIZEMOS, em contraste com o que imaginávamos que faríamos.

Um dos benefícios dessa abordagem de documentação emergente descrito por Tom de Lancey é:

Documentação se torna parte do processo de desenvolvimento, não uma atividade separada. Desde que a documentação seja realmente útil, todo a equipe tem interesse em mantê-la. Cada história tem uma tarefa separada para atualização da WIKI (um site do SharePoint que se conecta a cada história).

Mario Moreira escreveu um artigo sobre ajustar o tamanho da documentação no mundo da agilidade. Ajustar o tamanho é descrito por Mario Moreira como resposta às grandes quantidades de documentação que o projeto de software deve ter:

Ajustar o tamanho significa que o nível de esforço aplicado para escrever e manter a documentação somados ao valor da documentação escrita deveria ter um retorno sobre o investimento (ROI) muito maior, do que não ter essa informação rapidamente disponível (tal como, o esforço que seria necessário pára reconstruir a informação e o impacto de não ter essas informações para decisões atuais).

O artigo de Mario Moreira colabora guiando ao ajuste do tamanho da documentação. Algumas das sugestões são:

  • Documentação deve ter uma natureza colaborativa. Portanto não deve ser escrita por uma única pessoa até estar perfeita, e somente então ser compartilhada com os outros. Ao contrário, deve ser compartilhada muitas vezes durante projeto para ganhar conteúdo;
  • Focar somente na documentação boa o suficiente e evitar detalhamentos do "todo" feitos no início de projeto, que na sua maioria significam adivinhações e perda de tempo;
  • Documentação pode ter várias formas. Não é somente um documento word, documentação pode estar no Wiki, em ferramenta de planejamento agil, como comentários no código, e muito mais.

Como você faz sua documentação em agilidade? Quanto e quando?

Olá visitante

Você precisa cadastrar-se no InfoQ Brasil ou para enviar comentários. Há muitas vantagens em se cadastrar.

Obtenha o máximo da experiência do InfoQ Brasil.

Dê sua opinião

HTML é permitido: a,b,br,blockquote,i,li,pre,u,ul,p

Receber mensagens dessa discussão

O que documentamos by Paulo Vitor

Muito bom artigo, tive a experiência de documentar regras de negócio essenciais por e-mail inicialmente e depois em um arquivo word.

HTML é permitido: a,b,br,blockquote,i,li,pre,u,ul,p

Receber mensagens dessa discussão

HTML é permitido: a,b,br,blockquote,i,li,pre,u,ul,p

Receber mensagens dessa discussão

1 Dê sua opinião

Conteúdo educacional

Feedback geral
Bugs
Publicidade
Editorial
InfoQ Brasil e todo o seu conteúdo: todos os direitos reservados. © 2006-2014 C4Media Inc.
Política de privacidade
BT