Documentação Técnica

Com a chegada das metodologias ágeis e outras mudanças nos processos de desenvolvimento
de sistemas, vemos que algumas práticas dos processos anteriores tem sido ignoradas ou até mesmo
descartadas pelos times. Uma delas é a documentação técnica de software. Normalmente vemos
entrar no escopo dos projetos a elaboração de documentação de negócio, documentação do produto,
documentação de requisitos, e a partir daí vai para a mão do desenvolvedor que normalmente tem
um prazo apertado para resolver a situação. Em algumas empresas ela é vista como algo burocrático,
que rapidamente fica desatualizada devido às correções e melhorias, e que não agrega valor. Talvez
por causa de ferramentas usadas no passado, como a UML, que quando é confrontada com a
necessidade atual de “velocidade dos times” , torna fácil a decisão de não documentar.
Mas a falta de documentação traz seus efeitos colaterais:

- Falta de padronização
- Desnível de conhecimento entre os integrantes
- Refatorações constantes do código

Sem contar que a médio e longo prazo pode até causar a perda da tão almejada
“velocidade”.

O desafio aqui é gerar uma documentação técnica do que está implementado, mas ela deve
ser a mais simples, prática e fácil de manter possível, e principalmente, que gere valor à equipe.
Atualmente existem muitas ferramentas que geram documentação a partir da análise do
codigo fonte, mas ainda assim elas não substituem algumas boas práticas que os times podem utilizar
para ter uma documentação útil para todos. A questão é : o que deve ser documentado ? Essa
resposta pode variar muito, dependendo do tamanho e complexidade do projeto. Uma boa forma de
começar seria fazendo o seguinte questionamento:

- quais perguntas que as pessoas fazem repetidamente?

- quais informações são conhecidas somente por algumas pessoas específicas ?

As respostas para estas perguntas são provavelmente o que deve ser documentado. Veja alguns
exemplos de respostas, que dão um bom ponto de partida:
- Quem usa a solução ?
- Qual framework utilizado ?
- Qual a arquitetura da solução ?
- Onde está o código fonte ?
- Qual modelagem ?
- como acesso a aplicação ?
- como utilizo a API ?

Normalmente as pessoas que tem as respostas a essas perguntas se tornam a referência do time e
são as mais consumidas, causando o mau uso do tempo dela.
Considerando que o time deixou de fazer a documentação para poupar tempo, gastá-lo dessa forma
se torna contraditório!
Como fazer a documentação ? Essa também é uma questão que depende das necessidades
do time, composição e complexidade do projeto e até mesmo preferências pessoais. A regra geral é
evitar o uso de ferramentas ou processos morosos, a não ser que eles sejam impostos pelo setor ou
situação.
Uma boa forma de começar é utilizando uma antiga prática : o arquivo README na raiz de cada
projeto. Isso é facilitado até mesmo pelas ferramentas de versionamento de código como o GIT,
GITHUB E BITBUCKET. O arquivo não precisa conter informações detalhadíssimas sobre todo o
projeto, mas pode ser um bom início, inclusive atuando como ponto de conexão entre todas as
documentações relevantes contendo links para elas.
 Mais importante que a forma ou ferramentas, é entender se o time está confortável com a
produção e consumo da documentação. E lembrando de novo, ela deve ser útil. Pode não haver um
consenso entre o time sobre a forma de documentar, mas é imprescindível que se chegue num
acordo, e que a partir desse acordo todos sejam responsáveis e comprometidos em manter a
documentação.