Perguntas e respostas com Cyrille Martraire sobre o livro Living Documentation

No livro Living Documentation, Cyrille Martraire argumenta que deveríamos repensar como trabalhamos a documentação quando trabalhamos com sistemas de software, pois deveríamos adotar uma documentação que evolui no mesmo ritmo que o código-fonte. A documentação tradicional é um assunto enfadonho e frequentemente fonte de frustração, já que em grande maioria das vezes não podemos confiar nela, pois a informação que precisamos está ausente, obsoleta ou confusa.

Para Martraire, documentação significa conhecimento. Extraímos e transferimos conhecimento em conversas com outras pessoas, mas também adquirimos conhecimento "conversando" com as máquinas, onde escrevemos e rodamos testes que passam ou falham, e onde usamos a interface de uma aplicação e verificamos a resposta. A observação é uma terceira forma de adquirir conhecimento, onde aprendemos olhando como as pessoas trabalham e se comportam em diferentes situações, ouvindo as conversas com outras pessoas.

O conhecimento é necessário para evitar perda de tempo encontrando respostas para questões que já deveríamos saber responder. O conhecimento também é necessário para evitar tomadas decisões que poderiam potencialmente levar a débito técnico, maior custo de desenvolvimento e de manutenção de um sistema. Martraire aponta que a maior parte do conhecimento já existe, no código-fonte, nos testes, no comportamento da aplicação e nos cérebros de todas as pessoas trabalhando nele. É, basicamente, uma questão de encontrá-lo e explorá-lo.

Na primeira parte do livro, Martraire descreve os quatro princípios básicos da documentação viva. Ela é confiável, requer pouco esforço, é colaborativa e precisa. A documentação viva permite que os desenvolvedores foquem em fazer um trabalho melhor ao mesmo tempo que a documentação vai sendo criada.

Em muitos capítulos, Martraire descreve várias formas de extrair as partes importantes do conhecimento de um sistema, além de ensinar como podemos criar a documentação, incluindo documentos de aparência tradicional, que estejam sempre atualizados com o mínimos de custo adicional. Como uma documentação viva deve evoluir sempre no mesmo ritmo do sistema, normalmente é criada por um processo de automação. Anotações e convenções são duas técnicas que permitem isso. Um glossário de termos usados em uma parte do sistema é um exemplo de documento que pode ser automaticamente extraído do código-fonte. Conhecimento e documentação, também podem ser construídos a partir de um sistema já em produção. Para melhor compreender um domínio, desenvolvedores trabalhando em uma aplicação deveriam utilizá-la e aprender sobre seu comportamento para os casos de uso mais comuns, mesmo em domínios complexos. Inspecionar um sistema distribuído em tempo real e agregar rastros em um gráfico de dependências de serviços também pode ser uma ótima forma para os arquitetos entenderem exatamente como o sistema funciona.

Nos capítulos posteriores, Martraire explica como documentação viva pode ajudar no design e arquitetura de um sistema, especialmente para equipes praticando arquitetura evolutiva, onde a mesma está evoluindo constantemente. Para equipes praticando DDD que tenham problemas na geração de um glossário vivo ou outra documentação relacionada ao negócio, é um sinal de alerta que sua forma de trabalhar com DDD está errada e que o código deveria ser reprojetado para refletir o domínio de negócio mais próximo da realidade. Ao usar as técnicas descritas no livro, as equipes normalmente começam as ver outras melhorias de design. Documentar decisões pode, com frequência, revelar fraquezas e encorajar mais reflexões e melhorias no design.

Por fim, Martrire fornece uma orientação sobre como introduzir a documentação viva em um novo ambiente e formas de documentar os sistemas legados. Durante a introdução de documentação viva, ele costuma recomendar um início lento e suave, sem a necessidade de pedir permissão aos superiores. Ao invés disso, a documentação deveria se tornar gradualmente uma parte natural do trabalho diário dos programadores. Os sistemas legados são geralmente valiosos, mas o conhecimento sobre eles não costuma estar prontamente disponível. Podem faltar testes ou não haver uma definição precisa do comportamento. Para superar isso, Martraire descreve algumas técnicas especialmente aplicáveis para sistemas legados.

InfoQ: Conte-nos um pouco sobre o livro.

Cyrille Martraire: O livro é resultado de vários anos de coleta de ideias e tentativas relacionadas a documentação em um ambiente ágil. A documentação sempre foi fonte de frustração para qualquer desenvolvedor. Nunca é "como devia ser" seja lá o que isso signifique. É hora de solucionar esse problema com respostas efetivas e aplicáveis, para que todos vivam em paz quanto a isso, fazendo as equipes serem mais efetivas e desenvolvendo software ao mesmo tempo.

Portanto, o livro é sobre compartilhar conhecimento com eficiência, ser mais efetivo, coletivamente e no longo prazo, além de desenvolver e evoluir software, significando que o livro também fala, de uma forma sutil, sobre design de software.

InfoQ: O que te motivou a escrever esse livro?

Martraire: O que desencadeou a escrita do livro foi os comentários entusiasmados após minhas apresentações nas quais mencionava algumas técnicas incomuns de documentação. Tendo sido desenvolvedor em várias empresas, passei diversos anos experimentando técnicas de documentação para tornar um design de software mais visível e encorajar melhorias nos designs. O livro foi uma conclusão natural para compartilhar isso de forma estruturada.

InfoQ: Qual é o público alvo e o que espera que aprendam?

Martraire: O livro é para profissionais de software que não têm medo de pequenas quantias de código, então é idealmente para líderes técnicos, arquitetos de código e automatizadores de testes. Aprenderão a documentar de formas diferentes, sem muita conversa, com técnicas que também são divertidas de serem aplicadas. Mas alguns leitores me dizem que aprenderam muito mais que isso!

InforQ: Você vê valor de negócio em documentação viva?

Martraire: Sim, pois isso é sobre acelerar as entregas. Equipes de software gastam tempo demais redescobrindo como as partes do sistema foram projetadas, o que fazem e como evoluí-las consistentemente.

InfoQ: Quais são as principais vantagens das equipes ou organizações que adotam a documentação viva?

Martraire: As equipes que adotam a documentação viva trabalham mais rápido, e também limitam a degradação do sistema. Quando se sabe como uma coisa foi projetada, é possível respeitar o projeto, ou alterá-lo com total compreensão do contexto. Isso é empoderador. E tem mais: uma vez que se dá atenção para o que está sendo documentado, a tendência é que o resultado seja melhor. Isso é muito importante!

InfoQ: O que vê como principais desafios?

Martraire: Um primeiro desafio é que, à primeira vista, a documentação não é a coisa mais empolgante das vidas dos desenvolvedores. Mas com a documentação viva ela se torna bem mais divertida, até ela se tornar outro problema, como uma nova oportunidade de procrastinar e deixar de fazer o trabalho chato.

InfoQ: Quando trabalhamos com documentação viva, estamos bem perto da base de código. É possível que especialistas de domínio e outros que estejam fora do núcleo da equipe possam ajudar na adoção de documentação viva?

Martraire: É verdade que as práticas de documentação viva tendem a favorecer a aproximação do conhecimento com a base de código, como fonte da verdade. Contudo, "colaboração" é um ingrediente chave da documentação viva, propusemos várias técnicas para garantir que o conhecimento relevante seja accessível por todos os envolvidos, especialmente por pessoas não técnicas. Por exemplo, temos glossários vivos e diagramas gerados automaticamente a partir do código fonte. Então sim, é para todos, não apenas desenvolvedores que fazem alterações na base de código aṕos uma discussão coletiva.

InfoQ: Você vê necessidade, ou alguma vantagem, de bibliotecas com recomendação de anotações ou talvez inclusas em uma linguagem ou plataforma, como por exemplo uma biblioteca de anotações de DDD?

Martraire: Seria uma vantagem ter uma biblioteca reutilizável, considerando que pudéssemos criar uma que se adequasse ao estilo de programação e ferramentas específicas de qualquer um. Por enquanto, sugiro criar suas próprias bibliotecas dentro de cada empresa, departamento ou equipe. Quem curte programação funcional e DDD em Java, por exemplo, criaria sua própria biblioteca de anotações em Java. Mas para quem gosta de Event Sourcing com um framework baseado em anotações, muitas já estão disponíveis, não sendo necessário adicionar muita coisa. Mas para quem não está fazendo tudo isso, uma biblioteca pareceria algo estranho.

InfoQ: Você acha que documentação viva algum dia vai se tornar popular dentro da comunidade de software?

Martraire: As tecnologias com certeza ficarão no mainstream, a única questão é se o nome "documentação viva" vai ser popular algum dia. Mas isso é o de menos.

InfoQ: O que vê como principais empecilhos à adoção de documentação viva pela comunidade de software?

Martraire: A documentação em geral tem sido negligenciada por anos. Além disso, o manifesto ágil é normalmente mal interpretado. Nunca foi dito para não fazer nenhuma documentação. Mas as técnicas para conciliar seus objetivos com os valores ágeis não são bem conhecidas. O livro busca fechar esse gap!

Sobre o autor do livro

Cyrille Martraire é uma conhecida autoridade do Domain-Driven Design, artesanato de software e palestrante frequente em conferências internacionais. Perito em mercado de capitais, trabalhou e liderou vários projetos importantes. É CTO e cofundador da Arolla, uma consultoria francesa especializada em desenvolvimento de software.