Como documentar um sistema para vender (e não virar suporte eterno)

Vendedor experiente sabe: o lucro de um projeto não está só no preço, está em quantas horas de suporte ele consome depois. Dois projetos vendidos pelo mesmo valor podem ter margens completamente diferentes — e a documentação é quase sempre a explicação.

Comece pelos requisitos, sem rodeio

A primeira coisa que o comprador precisa saber é se o projeto roda no ambiente dele. Seja explícito:

• Versão mínima da linguagem
• Banco de dados e versão
• Extensões obrigatórias
• Se precisa de acesso a terminal ou se roda em hospedagem compartilhada
• Serviços externos necessários e se têm custo

Essa lista evita a pior situação possível: alguém compra, descobre que não roda e pede reembolso irritado.

Instalação em passos numerados

Nada de mandar configurar o banco de dados. Escreva o que clicar, o que digitar, o que esperar ver. Assuma que a pessoa é competente mas nunca viu o seu projeto.

Um teste honesto: entregue para alguém que não conhece o sistema e observe em silêncio. Todo ponto onde a pessoa hesita é um parágrafo faltando.

Diga o que mudar para o sistema virar do comprador

É a seção mais valorizada e a mais esquecida. Onde trocar o logo, as cores, o nome, os textos, o e-mail de contato. Se há um arquivo de configuração central, diga isso na primeira linha.

Explique a estrutura em um parágrafo

Não precisa documentar cada arquivo. Precisa dizer onde ficam as rotas, onde fica a lógica de negócio e onde ficam as telas. Com isso qualquer desenvolvedor acha o resto sozinho.

Documentação boa não é a que explica tudo. É a que responde as cinco perguntas que todo mundo faz.

Antecipe os erros comuns

Você já sabe onde as pessoas travam — são sempre os mesmos três ou quatro pontos. Uma seção de problemas comuns com sintoma e solução corta boa parte das mensagens que você receberia.

Seja honesto sobre os limites

Diga o que o projeto não faz. Parece contraintuitivo, mas evita a venda errada — que sempre termina em reembolso, avaliação ruim e horas perdidas. Um comprador que sabe o que está levando reclama menos e avalia melhor.

Mantenha o changelog

Cada versão com o que mudou, em linguagem clara. Isso mostra que o projeto está vivo e é o que faz o comprador confiar em comprar de você de novo.

Documentar bem dá um dia de trabalho. Suporte mal documentado dá um dia por mês, para sempre.