AgileFAQ #1: E a documentação?

Quando fazemos apresentações sobre ágil ouvimos muitas vezes as mesmas velhas perguntas. Confesso que às vezes acho um pouco … digamos… chato responder a essas perguntas pela vigésima vez (#prontofalei). Mas, cá pra nós, não dá pra negar que essas perguntas são chave para o entendimento da filosofia ágil.

Por isso resolvi iniciar incitar essa série de posts aqui na visão ágil, com o intuito de que tenhamos uma muleta prática em que nos apoiar toda vez que precisarmos responder (ou evitar😉 ) essas perguntas.

De minha parte, acho que a pergunta mais frequente de todas, campeã indiscutível, é a velha “e a documentação?”. Então resolvi começar a séria com ela.

 

 Já tive várias respostas para essa pergunta. A primeira que me vem à mente hoje em dia é: mas quem foi afinal que falou pra essa gente que nós não documentamos nada?!  Esse é na verdade apenas mais um preconceito bobo cultivado pelo telefone sem fio de pessoas que ouvem cantar o galo mas não sabem onde.

Talvez seja por que o manifesto proclama que “software funcionando vale mais que documentação compreensível”. Quando essas frases ecoam por aí parece que o diz-que-me-disse das pessoas acaba esquecendo de levar junto a frase final do manifesto. (Não vou copiá-la aqui. Vai lá e lê!).

Não é que agilistas não gostem de documentação. Parem com isso! O que não gostamos é do mal hábito que se cultivou em basear absolutamente tudo em documentação formal. Trata-se de uma cultura que se desenvolveu por várias razões em nossa indústria nas últimas décadas, mas que simplesmente não faz mas sentido.

Bem, pra falar a verdade, verdade mesmo, XP realmente diz que a melhor documentação que existe sobre o código fonte é o próprio código fonte. Mas isso de forma alguma deve ser interpretado como “se você escreve documentos, então você não faz XP”. Melhor seria entende-la como “trabalhe no sentido de criar código auto explicativo que dependa cada vez menos de artefatos não integrados ao código”.

A maioria das comunicações que nos acostumamos a fazer com documentos formais seriam muito mais eficientes se feitas pessoalmente, conversando, ou até mesmo por telefone. Documentos formais são caros e chatos de manter atualizados. São raras as situações em que são realmente necessários.

Uma das melhores respostas que já ouvi para a pergunta foi dada pelo Juan Bernabó, em um podcast publicado pela ImproveIT (não me pergunte qual), onde alguém perguntou algo como “mas que documentação vocês fazem em Scrum?” A resposta, de tão curta e direta, não chegou nem a ser entendida de primeira por quem perguntou: “a necessária”.

É isso. Se uma documentação é necessária, faz-se a documentação e pronto. Seja lá pelo motivo que for. Não é raro, por exemplo, encontrar clientes que simplesmente não dão o braço a torcer e querem porque querem a documentação dos casos de uso antes que se comece a desenvolver. O que fazer? 

Ora, faça as documentações! Que mal há nisso? Crie cartões ou post-it’s para “escrever a documentação do caso de uso CadastrarUsuário”, estime seu esforço e o coloque no backlog, para ser priorizado. Se seu cliente priorizar a documentação, assim será. O mais provável é que ele se convença, com uma ou duas iterações, de que ele na verdade não precisa daquilo… Mas é assim mesmo. Algumas vezes o caminho mais rápido é o mais comprido e tortuoso.

Acho que a lenda que diz que “ágil não documenta nada” poderia ser corrigida para “ágil recomenda que se reflita a respeito de quais documentações são realmente necessárias”.

Tenho certeza de que ainda existem muitas outras respostas para essa pergunta infame que tanto confunde as pessoas. O que deixei aqui foi apenas um ponto de partida para alguma reflexão e uma pequena provocação para que os colegas complementem com seus pontos de vista.

 

Sobre o Autor:

Bruno Pedroso

Bruno Pedroso

 

Bruno Pedroso é Bacharel em Ciência da Computação pela UnB, onde atualmente desenvolve seu projeto de mestrado em engenharia de software. Desenvolvedor com mais de 10 anos de experiência, atua hoje como coach de projetos e coordenador da área técnica da SEA tecnologia, dando grande enfoque à aplicação de valores e princípios XP.

11 thoughts on “AgileFAQ #1: E a documentação?

  1. Concordo Plenamente com você Bruno!

    Em em de meus projetos atualmente aconteceu exatamente isso.

    O cliente (interno, diga-se de passagem) bateu o pé socre a documentação e tal…. dizia que ‘deveríamos fazer um levantamento de todos os processos, um mapeamento completo de tudo o que seria possivel esperarmos do software…etc…etc…’

    Concordamos…. mas bastou dois releases e ele voltou atraz…agora dizendo…’é! acho melhor irmos desenvolvendo e analisando… assim posso acompanhar melhor o desenrolar do software…’

    Excelente Artigo…😉

  2. Pingback: ADSystems » E a documentação?

  3. Fui buscar no dicionário Aurélio:

    necessário [Do lat. necessariu.]
    Adjetivo.
    1. Que não se pode dispensar; que se impõe; essencial, indispensável;
    2. Que não pode deixar de ser; forçoso, inevitável, fatal;
    3. Que deve ser feito, cumprido; que se requer; preciso.

    Concordo que a documentação a ser gerada deva ser somente a necessária. Mas necessária para o quê e para quem? Na minha opinião, para três coisas:
    1) Ajudar a equipe a desenvolver o raciocínio na busca da solução;
    2) Comunicação entre os membros da equipe;
    3) Facilitar manutenções (evolutivas) futuras por outras pessoas/equipes.

    Penso que por causa do terceiro item, as empresas exageram na obrigatoriedade de documentação.

  4. Muito bom o texto Bruno!
    Qualquer iniciativa para ajudar o todo, sempre será bem vinda.

    Com relação a este trecho do texto “… Crie cartões ou post-it’s para “escrever a documentação do caso de uso CadastrarUsuário” …”, ainda pode vir a seguinte crítica: “Desde quando cartão e post-it é documentação?”

    Já escutei várias vezes isso, e muito tentei explicar, mas quando a pessoa que está argumentando contigo está apta a não querer entender, aí fica difícil tentar qualquer argumento.

    Mas valeu pelo texto, e que o blog continue ajudando sempre mais.

  5. Oi Bruno!

    Ótimo post. A clareza no tratamento desse assunto é realmente importante para evitar a propagação de mal entendidos.

    Temos que considerar que clientes e desenvolvedores possam ter diferentes visões da documentação que ‘é necessária’, no entanto, se o cliente (por seus motivos quaisquer) considera que ela tem valor e está disposto a pagar por esse valor, isso realmente precisa ser respeitado e levado em conta pelos desenvolvedores.

    Em minha experiência não costumo documentar tudo, no entanto, já trabalhei com regras e requisitos de tamanha complexidade que não utilizar diagramas e outros documentos simplesmente inviabilizaria o entendimento posterior (no dia seguinte!) do que foi desenvolvido. Como dar manutenção num caso desses? Como comunicar o que deve ser feito se a equipe está fisicamente separada? Somente com a documentação de apoio suficiente, adequada e nada mais que a necessária.

    Tomara que os demais itens do AgileFAQ sejam tão bons quanto esse!

    Abraço e parabéns!
    Jorge Ivan

  6. Caros amigos, ótimo idéia esta do FAQ e melhor ainda.. começando pelo calcanhar de Aquiles das dúvidas de métodos ágeis.

    Vou colocar um pouco da minha experiência aqui. Iniciei a pouco tempo meu primeiro projeto baseado em uma metodologia Ágil (SCRUM), mesmo sabendo que esta não é exatamente para desenvolvimento e sim gerenciamento, mas enfim. Estive antes em um projeto muito grande para o governo que era completamente baseado em Water-Fall, mas se dizia RUP. O problema é que tínhamos nada menos que 15 artefatos para produzir antes de iniciar alguma codificação.

    Era um absurdo… todos os documentos ficavam desatualizados, os diagramas não batiam uns com os outros… enfim era caótico, tanto que o projeto foi abortado e TODA a documentação foi para o LIXO. Sendo assim neste meu novo projeto como tive alguma influência na determinação do processo, chegamos aos seguintes documentos; casos de uso SOMENTE para funcionalidades complexas que envolvem muitas regras de negócio; diagrama de classes e as regras do negócio propriamente. Temos também a facilidade de confeccionar alguns outros diagrama da UML para poder subsidiar o desenvolvimento.

    O que gostaria de registrar é que a minha posição no projeto é mais técnico/gerencial, pois sou o PO do projeto e responsável técnico (analista). O que me surpreendeu foi que alguns de nossos desenvolvedores reclamaram que não havia casos de uso escritos para CRUD!!! Funcionalidades estas que nem mesmo regras de negócio tinham para a entrada/edição de dados. O que me veio a mente foi que as pessoas ainda sentem a necessidade de documentações completas, densas, dizendo como elas devem agir. É como se fosse um manual, primeiro desembale o produto, agora ligue-o na tomada, etc… isso é um absurdo.

    Seres humanos são criaturas das mais inteligentes, capazes de feitos notáveis, fico muito preocupado quando vejo um cenário destes, onde se não está escrito eu não si o que fazer.

    Hoje em dia temos diversas ferramentas CASE altamente acopladas com ferramentas IDE que ambas podem facilmente resolver o problema de documentação (falo em diagramas ML) “sincronizada”. Eu acho que no fundo é exatamente o que foi dito no artigo, que documentação fazer, a necessária (ou a que foi mandada), mas vamos agir com bom senso e usar a cabeça e algumas ferramentas para o auxílio.

    Abraços a todos.

  7. Bruno,

    Sem dúvida um assunto muito interessante.
    Assim como a colocação que o Marcelo fez.

    Gosto da idéia de trabalhar com testes de aceitação, que tornam-se documentos executáveis.

    Desta maneira você o comportamento do software fica documentado e principalmente, consegue-se a garantia de um funcionamento correto, de maneira automatizada.

  8. Pingback: Perguntas e Resposta « AgilDev

  9. Muita gente quer documentação para ter algo em quê se escorar!

    Já vi neguinho dizendo: “mas a documentação dizia para fazer assim… por isso que fiz.”😮

    Menos documentação => mais responsabilidade => mais risco => mais reflexão => decisão.


    []s.
    Vinicius Assef.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s