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.

Tags: , , , , , , , , , , , , , ,

13 Responses to “Alguns pensamentos sobre “documentação ágil””

  1. Bruno says:

    Parabéns pelo artigo Guilherme,

    eu apenas adicionaria que criar testes e gerar a documentação dos mesmos automaticamente, assim como rspec do ruby faz, é o melhor dos mundos, ou seja ter documentação executavel ligada ao codigo.

    abraços

  2. Maneiro GC. Excelente contribuição!

  3. Guto Maia says:

    Excelente artigo GC. Legibilidade de código é algo fundamental e complexo de se manter ao longo tempo, não em função das partes mas em razão do todo. O design arquitetural tem que caminhar junto com a simplicidade das partes. A arquitetura não pode esconder a intenção do código e sempre que isso ocorrer é necessário um redesign. Redesign não é aprimorar o atual, mas sim desatar alguns nós para fazer outros.

    Redesigns geram mais documentação e um principalmente a oportunidade de se documentar o estimulo que justifica o redesign.

  4. [...] Alguns pensamentos sobre “documentação ágil” Guilherme Chapiewski (tags: agile) EtiquetasCategoriasmiudezas Uncategorized   [...]

  5. Guilherme,

    Concordo com a maioria dos pontos, mas tenho mudado um pouco minha percepção sobre documentação no código desde que li o código do JQuery. Cada linha, ou conjunto de, tem um comentário explicando porque ela existe e tal.

    E isso foi bem importante para entender tudo que está lá, mais do que qualquer documentação deles num wiki ou gerador de documentação. Dá até pra comparar, pois tive muito mais dificuldade de ler o código do Mootools do que o do Jquery.

    Abs,
    Bruno

    • Legal, Bruno, realmente é um caso interessante.

      A única questão aí é que isso gera um trabalho a mais. Eles precisam manter os comentários atualizados e garantir que os contribuidores também vão fazê-lo. Pode ser que eles tenham chegado a alguma conclusão do tipo “ferrou, o código é complicado mesmo, a gente não consegue mudar e se a gente não comentar tudo, ninguém vai conseguir usar ou contribuir com o projeto (o que seria horrível)”. Enfim, estou só chutando, mas pode ser que tenha algum motivo, sei lá.

      No geral acho que o mais certo é: se você não tem um motivo muito bom para deixar comentários no código, remova-os e torne o código mais fácil. Não somente por questões de legibilidade, mas também porque quanto mais fácil for o código mais fácil será de adicionar novas funcionalidades (ou no caso do JQuery, mais fácil vai ser para outras pessoas poderem contribuir também). :)

      [ ]s, gc

      • seufagner says:

        Na verdade a grande questão sobre comentários é sobre O QUE você está codificando.

        Quando você escreve uma gem/framework, acredito que você DEVE documentar sim. E bem. Pois será algo utilizado – supostamente – as mais diversas estirpes de pessoas.

        Para auxiliar existem geradores de documentação que automatizam isso, claro -rdoc, javadoc, etc – . Neste caso, acredito que faz parte da codificação deixar tudo bem documentado.

        Quanto à legibilidade do código, ela deve sempre existir e esta característica, principalmente na escolha dos nomes, é um dos pilares do DDD.

  6. Bruno,

    concordo com você sobre a importância dos comentários em alguns casos. Mas o problema é que nem sempre eles estão atualizados. Em geral, acho mais interessante refatorar o código para torná-lo mais claro do que adicionar comentários.

  7. No Refactoring, tem uma frase legal, algo como “Comentário é desodorante de código ruim”.

    Acho legal quando você diz que as pessoas acabam não pensando no que estão fazendo e seguindo o que já foi definido. Esse é o grande perigo de um processo formal (e não só quando falamos de documentação).

    O mindset Ágil é bem diferente. O lance é documentar o mínimo suficiente, levando em conta o contexto. É preciso sempre lembrar que o propósito de você documentar é comunicar o que você fez (ou oque precisa ser feito) para alguém distante temporal ou fisicamente.

    Alistair Cockburn fala que Ágil foca mais em Disciplina, Habilidade e Entendimento do que em Processo, Formalidade e Documentação.

    Disciplina é trabalhar de forma consistente. Processo é seguir passos pré-definidos. Ter disciplina é mais importante que seguir um processo.

    Formalidade é uma tentativa de contornar a falta de Habilidade, tentando tornar os passos mais repetíveis. Mas perde-se o contexto e, por isso, a eficácia. Então, habilidade é preferível à formalidade.

    Documentação é uma das formas de se levar ao Entendimento, mas o foco deve ser o entendimento. Documentação é apenas um meio e, em boa parte dos casos, não é o mais eficiente. Enfim, o que importa é o entendimento, não o documento.

    O lance é atacar a causa raiz dos problemas, tanto quando o problema é comunicar a intenção do código com um outro desenvolvedor, como quando o problema é entender o que o cliente quer (ou quis) com aquele software.

  8. Guilherme,

    Ótimo post para lembrarmos dos motivos de pensarmos duas vezes antes daquelas famosas documentações.

    Dentre as dicas, vejo bastante a Documentação Perecível, Documentação não fazendo parte do “Definition of Done” e vejo bastante os famosos “Code Smell”.

    Dentre estes pontos acho que a documentação de código via comentário em certas ocasiões é necessária quando trabalhamos com código legado.
    Com toda certeza ele deve ser refatorado, seguir uma linha do domínio do usuário e ter o entendimento fácil, porém ainda tem aquele momento que realmente não é possível você modificar naquele momento tal código difícil de ler e creio que neste caso cabe uma breve descrição do que aquele “pequeno monstro” pretende fazer.

    Não gosto dessa abordagem mas no dia a dia me encontro com ela de vez em quando.

    Gostei também do resumo em uma frase do Alexandre Aquiles: “Documentação é uma das formas de se levar ao Entendimento, mas o foco deve ser o entendimento”.

    Abraços!

  9. camilo lopes says:

    excelente post guilherme!! por acaso cair no seu post, e tenho seguido essa linha abordada acima. De fato documentar todo um sistema não faz muito sentindo até pq as regras de negocios mudam, os deadlines sem sempre incluem, “atualizar documentação” e o cliente não vai querer pagar por isso.
    muito bom o post. Outro ponto que achei interessante é dos comentarios, citei o mesmo que vc falou :”melhor refatorar que inserir um comentario”, mas a resposta que recebi foi: “os comentarios foram feito para ser usado, não há problemas em comentar”.
    p.s: parabens! pelos posts, começei estudar Agile através de seus posts, grande motivador :D

    abracos,

  10. [...] fazer vídeos que demonstram como utilizar as funcionalidades mais avançadas. Para ler  Alguns pensamentos sobre “documentação ágil”, do Guilherme Chapiewski Gostar disso:GosteiSeja o primeiro a gostar disso. ▶ Nenhuma [...]

Leave a Reply