Documentação de software: o que exigir de quem desenvolve

Uma boa documentação de software é a que permite outra pessoa assumir o sistema sem entrevistar quem o escreveu. Esse é o teste — não o número de páginas, não a ferramenta escolhida, não o capricho do diagrama.

Quem contrata desenvolvimento raramente cobra isso na hora certa. O assunto costuma aparecer no fim do projeto, quando o time que construiu já está de saída — e aí a documentação sai cara, incompleta e escrita de memória. Este guia mostra o mínimo exigível em cada fase, o que não vale a pena documentar, e como testar se o que você recebeu é suficiente.

O que a documentação de software precisa resolver

Ela resolve um problema só: reduzir a dependência de pessoas específicas. Formato, ferramenta e padrão são consequência disso, não o objetivo.

Três situações cobram essa conta, sempre:

• o desenvolvedor que conhecia o sistema sai, ou o contrato com o fornecedor termina;
• alguém precisa mexer numa parte que ninguém toca há um ano;
• uma decisão antiga precisa ser revista e ninguém lembra por que foi tomada.

Documentação que não ajuda nessas três horas é enfeite. O framework Diátaxis organiza isso bem ao separar quatro modos com propósitos diferentes — tutorial, guia prático, referência e explicação. A confusão mais comum é escrever explicação quando o leitor precisava de referência, e vice-versa.

O mínimo exigível, fase por fase

No nosso processo de cinco fases, cada etapa produz um artefato que sobrevive a ela. Use isto como checklist de cobrança, independente de quem esteja desenvolvendo:

1. Descoberta e auditoria — o registro do escopo acordado, das restrições e dos sistemas existentes que o projeto precisa respeitar. É o documento que evita a discussão de "isso estava combinado?" seis meses depois.
2. Arquitetura e planejamento — o desenho dos serviços e do modelo de dados, acompanhado das decisões que levaram até ele. Um Architecture Decision Record resolve isso em uma página por decisão: o contexto, a escolha e a consequência aceita.
3. Engenharia — um README que faz o projeto rodar do zero numa máquina limpa, incluindo variáveis de ambiente e dependências externas. Se falta um passo, ele é descoberto no pior momento possível.
4. Testes e revisão — o que está coberto por teste automatizado e, principalmente, o que não está. A lista do que não é testado vale mais do que a do que é.
5. Deploy e suporte — o runbook de produção: onde o sistema roda, como sobe uma nova versão, como se faz rollback e o que checar quando algo cai.

Repare que nenhum desses itens é um documento de cem páginas. São cinco artefatos curtos, escritos no momento em que a informação ainda está fresca.

O que não vale a pena documentar

Documentação também tem custo de manutenção, e documento desatualizado é pior que documento ausente — ele mente com autoridade. Fica de fora:

• O que o código já diz. Comentário que narra a linha abaixo envelhece junto com ela.
• Passo a passo de tela. Interface muda a cada duas semanas; captura de tela em documento é dívida garantida.
• Qualquer documento sem dono. Se ninguém tem a obrigação de atualizar, ele já nasceu vencido.

A lógica de corte é a mesma do desenvolvimento de MVP: manter o essencial com profundidade vale mais que cobrir tudo pela metade.

O teste do desenvolvedor novo

Existe um jeito barato de saber se a documentação de software que você recebeu é suficiente. Entregue só a documentação a alguém que nunca viu o projeto e peça três coisas:

1. subir o ambiente e rodar o sistema localmente;
2. encontrar onde uma regra de negócio específica acontece;
3. explicar por que uma decisão técnica importante foi tomada daquele jeito.

Marque quantas vezes essa pessoa precisou perguntar algo a alguém. Cada pergunta é um buraco documentado no lugar errado — e é exatamente esse buraco que vira custo quando a pessoa que sabia a resposta não estiver mais disponível.

Documentação e a escolha de quem desenvolve

Vale inverter a pergunta na hora de contratar: em vez de pedir a proposta mais barata, peça para ver a documentação de um projeto que o fornecedor já entregou. A resposta diz mais sobre risco de dependência do que qualquer cláusula de contrato.

Na LW Forge, cada fase do nosso processo de desenvolvimento entrega o artefato correspondente durante o projeto, não depois dele — inclusive o handover na fase de deploy e suporte. Se você está avaliando um parceiro de engenharia e quer entender como isso funciona no seu caso, fale com a gente.