Documentação de software: o mínimo que impede você de ficar refém

Toda proposta promete documentação. Quase nenhum projeto entrega a que foi prometida, e boa parte da que é entregue ninguém lê.

A reclamação que ouvimos de quem troca de fornecedor quase nunca é "a documentação está incompleta". É mais direta: "não sei o que esse código faz".

A pergunta certa não é quanto documentar. É: o que precisa existir para outra pessoa conseguir continuar?

As cinco coisas que importam

1. Como subir o ambiente do zero. Um documento que leva alguém de máquina limpa a sistema rodando. Versões, variáveis, dependências, credenciais — onde estão, não quais são. É o item mais valioso e o mais frequentemente ausente.

Teste honesto: entregue para alguém que nunca viu o projeto e peça para seguir. O que essa pessoa perguntar é o que falta.

2. O desenho das decisões, não do código. Por que foi feito assim. Por que não foi feito do jeito óbvio. Qual alternativa foi descartada e por quê.

O código diz o que faz; ele não diz o que foi tentado antes e não funcionou. É a informação que mais se perde e a mais cara de redescobrir.

3. As integrações, com contrato e dono. Cada sistema com que o seu conversa: o que entra, o que sai, em que formato, com que frequência, e quem é a pessoa do outro lado. Nome, não área.

4. O que acontece quando dá errado. Onde ficam os logs. O que significam os erros mais comuns. Quem avisar. Como refazer um processamento que falhou. Isso vale mais do que o diagrama de arquitetura, e quase nunca está escrito.

5. O repositório, com histórico. Não é documento, mas é o item que define se você fica refém. Código entregue em .zip no fim do projeto não tem histórico, não tem o porquê de cada mudança, e não permite voltar atrás.

O que é desperdício

Documento que repete o código. "A função calcularTotal calcula o total." Envelhece no primeiro refactor e ninguém atualiza.

Diagrama de tudo. Diagrama vale para o que é difícil de entender lendo o código — fluxo entre sistemas, máquina de estados. Diagrama de classe gerado automaticamente é enfeite de proposta.

Manual de usuário de 200 páginas. Ninguém lê. Vídeo de três minutos por tarefa resolve melhor.

Documentação escrita no fim. É a pior de todas, porque é escrita por quem já esqueceu o motivo das decisões — quando é escrita.

Como garantir no contrato

A frase "a documentação será entregue ao final do projeto" não garante nada, porque no final do projeto todo mundo está atrasado e a documentação é a primeira coisa a cair.

O que funciona:

• Documentação é entregável de cada fase, não do projeto. Fase não é aceita sem ela.
• O repositório é seu desde o primeiro commit. Não "será transferido ao final".
• Transferência de conhecimento com horas reservadas no cronograma, com data, não

"se houver necessidade".

• O último pagamento fica vinculado ao teste do item 1: alguém de fora sobe o

ambiente seguindo o documento.

Esse último é o que mais muda comportamento. Documentação cuja qualidade é testada tende a existir.

O teste do ônibus, versão honesta

A pergunta clássica é "o que acontece se o desenvolvedor principal for atropelado por um ônibus?". Na prática o cenário é mais banal: ele pede demissão, ou o contrato acaba, ou a empresa troca de fornecedor.

O teste que vale: pegue alguém que não participou e peça para implementar uma mudança pequena. Uma semana de trabalho de verdade mostra mais do que qualquer auditoria de documentação.

Se essa pessoa consegue, você não está refém. Se ela precisa perguntar o tempo todo para quem escreveu, você está — e a documentação existente é teatro.

Como trabalhamos

Documentação técnica e funcional é entregável obrigatório por fase, o código vive no repositório do cliente desde o primeiro dia, e a transferência de conhecimento está no escopo com horas reservadas.

Não porque somos generosos, mas porque é o que torna possível você trocar de fornecedor sem recomeçar — e cliente que fica por não conseguir sair não é cliente, é refém.