Documentação técnica

A documentação técnica é uma das etapas que eu identifico como importantes para o desenvolvimento de software, principalmente quando trabalho com novos projetos. É o fio que une a equipe de desenvolvimento ao cliente, fazendo com que as visões e necessidades de projeto estejam alinhadas.

Essencialmente, essa é uma atividade executada por profissionais especializados em produto, no entanto, a documentação inicial também pode ser desenvolvida por pessoas desenvolvedoras de software, pois está diretamente relacionada ao dia-a-dia do processo de desenvolvimento.

O manifesto ágil, orienta que as documentações que forem criadas devem ser somente as mais essenciais e necessárias para o desenvolvimento do produto (Cockburn, 2007). Eu concordo fortemente com esse posicionamento, e acredito que o desenvolvimento de documentação não pode ser negligenciado, pois pode gerar inúmeros benefícios, como os definidos por Highsmith:

• Facilitar a comunicação e colaboração;
• Melhorar a transferência de conhecimento;
• Preservar informações históricas;
• Ajudar a melhorias em progresso;
• Satisfazer a necessidades legais e regulatórias;

Além disso, também seriam bons pontos:

• Facilidade em negociações com o cliente;
• Facilita o onboarding de novos colaboradores;
• Facilita a manutenção das regras de negócio criticas;

Ainda segundo Highsmith, é importante pontuar que a iteração entre as pessoas não deve e não pode ser substituída pela documentação, os desenvolvedores no dia-a-dia continuarão atuando em pair programming, ou em dúvidas de negócio. Porém com menos dúvidas triviais, que poderão ser verificadas facilmente na documentação.

Contudo, como a diferença entre o remédio e o veneno é a dose, é interessante observar que a documentação pode ser extremamente negativa, se for feita de forma exagerada ou estiver relacionada a informações que não voltarão a ser necessárias, pois consumirá o tempo da equipe e poderá atrasar o projeto.

Então quer dizer que é só fazer uma documentação inicial e codar loucamente ?

Não! É essencial que a documentação seja mantida atualizada, conforme as necessidades de cada projeto em específico. Por exemplo, no desenvolvimento de um sistema embarcado, as características dos componentes eletrônicos devem ser documentadas para novas aquisições. E essa atualização poderá ser de responsabilidade do projetista, do gestor ou até mesmo do comprador. Para casos assim específicos, onde podemos ter diferença em novas produções do produto, não interessa quem fará a documentação, mas alguém deverá realiza-la.

Em projeto de software, manter a documentação atualizada será, na maioria das vezes, responsabilidade do desenvolvedor. Tem alguns pontos que eu considero essenciais, e que devem estar muito claros, para o desenvolvimento de novos projetos:

• Definição ampla de ferramentas, e descrição de como executar o programa;
• Verificação de todas as funcionalidades que deverão ser desenvolvidas inicialmente;
• Requisitos funcionais, que serão aplicados para cada funcionalidade. Por exemplo, um filtro de tempo.
• Regras de negócio, que delimitam regras específicas para cada funcionalidade. Por exemplo, uma tela que só será acessada por um perfil específico de usuário.
• Casos de uso, que determinam o fluxo de ações e reações para com o cliente para determinados cenários. Por exemplo, o cliente quer se cadastrar em uma funcionalidade, quais são as telas que ele caminhará.
• Escopo da arquitetura geral.

Alguns desses pontos, como as regras de negócio e os casos de uso, podem ter forte associação com características inerentes ao software, por exemplo uma configuração que deve ser habilitada. Por esse motivo, é interessante que os desenvolvedores estejam ativamente envolvidos nessas especificações.

Por fim, mas não menos importante, fica a minha contribuição para desenvolvedores que constantemente iniciam projetos novos. Se você quer facilitar o processo de documentação, acesse meu template no github, que uso normalmente como read.me para facilitar a leitura.

Se você gostou, deixe seu joinha. Se não gostou, deixe suas contribuições de melhoria.