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

> Documentação de software sem burocracia: o kit mínimo de arquitetura, operação, integrações e regras de negócio que tira o sistema da cabeça de uma pessoa só.

Fonte: https://pervian.tech/blog/documentacao-de-software-minima · Pervian Tech · publicado em 2026-10-01

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](https://pervian.tech/blog/propriedade-do-codigo-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:

| Campo | Exemplo do que escrever |
|---|---|
| Sistema externo | Plataforma de e-commerce, banco, transportadora |
| O que trafega | Pedidos, saldo de estoque, retorno de cobrança |
| Direção e frequência | Loja → sistema, a cada pedido aprovado |
| Como autentica | Chave de API, certificado digital, usuário e senha |
| Onde está a credencial | Nome do item no cofre de senhas, não a senha |
| Quem é o contato do outro lado | Área ou canal de suporte do fornecedor |
| Validade | Data de vencimento do certificado ou do token |
| O que acontece se falhar | Pedidos ficam na fila e são reprocessados; ou param |

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](https://pervian.tech/blog/senhas-e-chaves-de-api-no-codigo), 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](https://pervian.tech/blog/plano-de-recuperacao-de-desastres-para-sistemas) é 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](https://pervian.tech/blog/sistema-dependente-de-um-programador), 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](https://pervian.tech/blog/assumir-sistema-legado-sem-documentacao).

## 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](https://pervian.tech/blog/manutencao-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](https://pervian.tech/blog/trocar-de-fornecedor-de-software) 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](https://pervian.tech/servicos/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](https://pervian.tech/#contato).