Documentação de software: o mínimo que todo sistema precisa

O desenvolvedor que cuidava do sistema avisou que vai sair. Na reunião de transição, a diretoria descobre que ninguém mais sabe onde fica o servidor, qual senha libera a integração com o banco, por que o desconto do cliente atacadista é calculado daquele jeito e o que fazer quando a emissão de nota trava às sete da manhã. Tudo isso estava na cabeça de uma pessoa.

A reação comum é pedir "documentação completa". Duas semanas depois chega um documento de dezenas de páginas, com prints de tela e descrição de cada campo, que fica desatualizado no mês seguinte e que ninguém abre quando o problema aparece.

Os dois extremos falham. Sem documentação, a empresa depende de pessoas. Com documentação demais, ela depende de pessoas do mesmo jeito, porque o papel envelhece mais rápido do que o código. Este texto define um kit mínimo de documentação de software: o que todo sistema em produção precisa ter escrito, em que formato e como manter isso vivo sem virar burocracia.

A resposta curta: o kit mínimo

Se o seu sistema tiver estes seis itens atualizados, outra pessoa ou outro fornecedor consegue assumi-lo sem depender de quem o construiu:

1. Visão geral da arquitetura: um desenho simples e uma página explicando as partes do sistema e como elas conversam.
2. Como rodar e publicar: o passo a passo para montar o ambiente de desenvolvimento, rodar os testes e colocar uma versão em produção.
3. Mapa de integrações: com quem o sistema troca dados, em que direção, com que frequência e onde ficam as credenciais (sem as credenciais no documento).
4. Regras de negócio críticas: as regras que, se mudarem sem querer, causam prejuízo, multa ou cliente irritado.
5. Manual de operação: rotinas agendadas, backups, monitoramento e o que fazer nos incidentes mais prováveis.
6. Registro de decisões: por que as escolhas importantes foram feitas, para que ninguém desfaça uma decisão sem saber o motivo dela.

Cada item cabe em poucas páginas. O que importa não é o volume, é que a informação exista, esteja num lugar conhecido e bata com o sistema que está rodando hoje.

Documentação que ninguém lê x documentação útil

A documentação inútil tem padrões fáceis de reconhecer:

• Descreve o óbvio. "O botão Salvar salva o cadastro."
• Foi escrita uma vez, no fim do projeto. Reflete o sistema da entrega, não o de hoje.
• Mora num arquivo solto. Um documento no computador de alguém, num e-mail antigo ou numa pasta compartilhada de que ninguém lembra o nome.
• Mistura públicos. O manual do usuário, a especificação técnica e as senhas no mesmo arquivo.

A documentação útil faz o contrário. Ela registra o que não dá para descobrir olhando o sistema: o motivo de uma regra, a ordem certa de reiniciar os serviços, a dependência escondida entre o fechamento do caixa e a rotina noturna de estoque. E fica perto do código, versionada junto com ele, para que mudar um seja lembrete de atualizar o outro.

Um critério prático: escreva o que você precisaria saber às três da manhã, com o sistema fora do ar e quem o construiu de férias. O resto é opcional.

Visão geral da arquitetura

É o mapa do território. Uma pessoa técnica que nunca viu o sistema deve entender, em meia hora, quais são as peças e como elas se ligam.

O que precisa ter:

• Um diagrama simples com os blocos principais: aplicação web, aplicativo, banco de dados, rotinas agendadas, filas, serviços externos. Caixas e setas bastam; não precisa de notação formal.
• Onde cada parte roda: servidor próprio, nuvem, qual conta, qual região, qual ambiente.
• Tecnologias e versões: linguagem, framework, banco de dados, sistema operacional. Isso mostra rapidamente se algo está perto de ficar sem suporte.
• Os fluxos principais: o caminho de um pedido desde o site até a nota fiscal, por exemplo, em cinco ou seis passos.
• Onde estão os repositórios de código e quem tem acesso a eles.

Este último ponto parece detalhe, mas não é. Se o código está numa conta pessoal do desenvolvedor ou do fornecedor, a empresa não controla o próprio sistema. Vale conferir também o que o contrato diz sobre isso, assunto que tratamos em propriedade do código-fonte no contrato.

Como instalar, rodar e publicar

É o documento que mais economiza tempo e o mais negligenciado. Ele responde a três perguntas:

Como montar o ambiente de desenvolvimento. Que programas instalar, como obter uma cópia do banco com dados de teste (nunca dados reais de clientes sem anonimização), quais variáveis de configuração preencher. Um bom teste: uma pessoa nova consegue rodar o sistema na própria máquina no primeiro dia, seguindo só o documento?

Como rodar os testes. Qual comando, quanto tempo leva, o que significa quando um teste falha.

Como publicar uma versão. Quem pode publicar, qual é o passo a passo, como conferir que deu certo e, principalmente, como voltar para a versão anterior se algo der errado. Se a publicação depende de um roteiro manual longo, documentar é o primeiro passo; automatizar é o segundo.

Mantenha este documento junto do código, no arquivo de apresentação do repositório (o README). É o primeiro lugar que qualquer desenvolvedor abre.

Integrações e credenciais (sem expor segredos)

Integrações são onde o conhecimento mais se perde. O sistema conversa com o ERP, com o banco para baixa de boletos, com a transportadora, com o gateway de pagamento, com a plataforma de nota fiscal. Cada conversa tem detalhes que só aparecem quando quebram.

Para cada integração, registre:

A regra de ouro: o documento diz onde a credencial está, nunca qual ela é. Senhas, chaves e certificados ficam num cofre de senhas ou no gerenciador de segredos da nuvem, com acesso individual e registro de quem consultou. Senha colada em documento, planilha ou mensagem de chat é exposição de segurança, e, pela LGPD, um vazamento de dados pessoais por esse caminho é responsabilidade da empresa, não só da equipe técnica.

A coluna de validade merece atenção especial. Certificado digital vencido é causa clássica de sistema parado numa segunda-feira, e a data costuma estar anotada só na memória de alguém.

Regras de negócio críticas

O código mostra o que o sistema faz. Raramente mostra por que. E é o porquê que evita que alguém "corrija" uma regra que parecia errada mas atendia a uma exigência comercial, fiscal ou contratual.

Não tente documentar todas as regras. Documente as críticas, que são as que se encaixam em pelo menos um destes critérios:

• Mexem com dinheiro: cálculo de preço, desconto, comissão, juros, rateio.
• Mexem com obrigação fiscal ou legal: tributação por tipo de operação, prazos de retenção de dados, consentimento.
• Vêm de contrato com cliente ou fornecedor: condição especial de um cliente grande, prazo de entrega acordado.
• Já causaram incidente: se a regra quebrou uma vez, ela merece registro.

Para cada regra, uma ficha curta: o que ela faz em linguagem de negócio, um exemplo com números fictícios, a origem (quem pediu, qual área responde por ela) e onde ela está no código. Em regras fiscais, inclua quem validou com o contador. A equipe técnica implementa; quem define a regra tributária é a contabilidade.

Exemplo de ficha bem escrita: "Pedidos de clientes do tipo revenda acima de determinado volume recebem frete por conta da empresa. A regra foi pedida pelo comercial para a política de distribuidores. Responsável: gerência comercial. Implementada no módulo de cálculo de frete."

Manual de operação e incidentes

O sistema está no ar. O que alguém precisa saber para mantê-lo assim?

Rotinas agendadas. Lista do que roda sozinho, em que horário e o que acontece se não rodar: importação de pedidos, envio de cobranças, fechamento de estoque, geração de relatórios.

Backups. O que é copiado, com que frequência, onde fica, por quanto tempo é guardado e, o item que quase sempre falta, quando foi o último teste de restauração. Backup que nunca foi restaurado é uma hipótese, não uma garantia.

Monitoramento. Onde ver se o sistema está saudável e quem recebe os alertas.

Roteiros de incidente. Para os cinco ou seis problemas mais prováveis, um roteiro curto:

1. Como reconhecer o problema (sintoma que o usuário relata e o que aparece no monitoramento).
2. Primeira verificação a fazer.
3. Ação para restabelecer o serviço.
4. Quem avisar, dentro e fora da empresa.
5. Como confirmar que voltou ao normal.

"A emissão de nota parou" é um exemplo típico. O roteiro diz: verificar se o certificado venceu, se o serviço da Sefaz está instável, se a fila de notas está travada, e o que fazer em cada caso. Quem está de plantão não precisa adivinhar.

Contatos e acessos. Quem é o responsável técnico, quem é o substituto, como acionar o fornecedor de hospedagem e de cada integração.

Registro de decisões

É o item mais barato de manter e o que mais evita retrabalho. Cada decisão técnica relevante ganha um registro curto:

• Contexto: qual era o problema.
• Decisão: o que foi escolhido.
• Alternativas consideradas: o que foi descartado e por quê.
• Consequências: o que essa escolha facilita e o que ela limita.

"Usamos fila para importar pedidos da loja, em vez de chamada direta, porque a loja tem picos em promoção e o ERP não aguenta o volume de uma vez." Com isso, o próximo desenvolvedor não remove a fila achando que é complicação desnecessária.

Checklist: seu sistema tem o mínimo?

Responda sim ou não para cada item:

• Existe um diagrama atualizado das partes do sistema e de onde elas rodam?
• O código está em repositório controlado pela empresa, com acesso de mais de uma pessoa?
• Uma pessoa nova consegue rodar o sistema na própria máquina seguindo só o documento?
• O processo de publicação e de volta para a versão anterior está escrito?
• Cada integração tem ficha com direção, frequência, contato e validade da credencial?
• Nenhuma senha está em documento, planilha ou chat?
• As regras de negócio que mexem com dinheiro ou obrigação fiscal estão descritas com exemplo?
• Existe lista das rotinas agendadas e do que acontece se elas falharem?
• O backup foi restaurado com sucesso em teste recente?
• Há roteiro escrito para os incidentes mais prováveis?
• As decisões técnicas importantes têm registro do motivo?

Cada "não" é um ponto em que o sistema depende da memória de alguém. Se a maioria das respostas for "não" e quem conhece o sistema está de saída, a prioridade é registrar o conhecimento enquanto ele ainda está disponível. Se a pessoa já saiu, o caminho é outro, e o descrevemos em como assumir um sistema legado sem documentação.

Como manter a documentação viva

Escrever o kit mínimo leva pouco tempo. O desafio é que ele continue verdadeiro daqui a um ano. Alguns mecanismos que funcionam:

• Documentação junto do código. Arquivos de texto no próprio repositório, versionados. Quando o código muda, a revisão da mudança pergunta: a documentação precisa mudar também?
• Faz parte da definição de pronto. Uma tarefa que altera integração, regra crítica ou processo de publicação só está concluída quando o documento correspondente foi atualizado.
• Atualize no incidente. Todo incidente resolvido termina com uma pergunta: o roteiro ajudou? Se não existia, escreva agora, enquanto o problema está fresco.
• Teste com quem chega. A melhor revisão da documentação é uma pessoa nova tentando segui-la. Onde ela travar, falta informação.
• Revisão periódica curta. Uma vez por trimestre, alguém confere datas de validade de certificados, contatos e acessos.
• Um responsável nomeado. Não precisa escrever tudo, mas responde pela documentação estar em dia.

Esse cuidado faz parte da rotina de qualquer sistema em produção, junto com atualizações e melhorias contínuas, como detalhamos em manutenção evolutiva de software.

O que exigir de quem desenvolve para você

Se o sistema é feito ou mantido por um fornecedor, a documentação mínima deve ser entregável do projeto, não cortesia. Combine na contratação quais documentos fazem parte da entrega, que eles fiquem no repositório da empresa, que sejam atualizados a cada entrega que altera o que descrevem e que haja uma transição assistida se o contrato terminar. Isso não é desconfiança: é o que permite trocar de fornecedor ou internalizar o sistema sem recomeçar do zero.

Perguntas frequentes

Quem deve escrever a documentação de um sistema?

Quem constrói e mantém o sistema escreve a parte técnica, mas a documentação de software precisa de um responsável nomeado que garanta que ela esteja em dia. Regras de negócio críticas devem ser validadas pela área que responde por elas, e regras fiscais pela contabilidade, porque a equipe técnica implementa, mas não define essas regras.

Onde guardar a documentação de software?

O melhor lugar é o próprio repositório de código, em arquivos de texto versionados junto com o sistema, começando pelo README. Assim, cada mudança no código lembra de atualizar a documentação. Senhas e chaves nunca ficam ali: a documentação de software indica onde a credencial está no cofre de segredos, não qual ela é.

Documentação de software é obrigação do fornecedor?

Só se estiver no contrato. Quando um fornecedor desenvolve ou mantém o sistema, a documentação mínima deve constar como entregável, ficar no repositório da empresa contratante e ser atualizada a cada entrega que altera o que descreve. Isso permite trocar de fornecedor ou internalizar o sistema sem recomeçar do zero.

Com que frequência a documentação precisa ser atualizada?

A documentação de software deve ser atualizada sempre que uma mudança altera o que ela descreve, como uma integração, uma regra crítica ou o processo de publicação, e também depois de cada incidente. Uma revisão periódica curta, por exemplo trimestral, ajuda a conferir validade de certificados, contatos e acessos que mudam sem relação com o código.

Como a Pervian Tech trabalha documentação

Na Pervian Tech, documentação faz parte do trabalho de arquitetura de software, não é uma etapa no fim do projeto. Os documentos nascem junto com o código, ficam no repositório do cliente e são atualizados a cada entrega que muda o que descrevem. Quando assumimos um sistema que já existe, começamos levantando esse kit mínimo, porque é ele que mostra onde estão os riscos de dependência de pessoas.

Cada sistema tem integrações, regras e rotinas diferentes, então o conjunto de documentos é ajustado sob medida ao que a operação realmente precisa. O investimento é definido sob consulta, depois de um diagnóstico inicial gratuito. Se o seu sistema hoje vive na cabeça de uma ou duas pessoas, fale com a gente.