Documentação de software: o que exigir do seu time de dev
Documentação de software é a diferença entre ser dono do seu sistema e alugá-lo de quem detém o conhecimento. O que exigir, e como saber se é boa, quando você não lê código.
Um fundador com quem trabalhamos herdou uma base de código quando o seu único desenvolvedor saiu com duas semanas de aviso. O app rodava bem. Esse era o problema. Ninguém conseguia mexer nele. Não havia nota de como configurá-lo, nenhum mapa de como as peças se encaixavam, nenhum registro de por que o fluxo de pagamento tinha sido feito daquele jeito estranho. O próximo desenvolvedor passou cinco semanas fazendo engenharia reversa do que algumas páginas de texto teriam explicado em uma tarde. O fundador pagou duas vezes: uma em honorários, outra no lançamento com o cliente que atrasou.
Documentação de software é o registro escrito de como um sistema é construído, operado e mantido. São as instruções de configuração, o mapa de como as partes se conectam, as notas sobre por que decisões-chave foram tomadas e os passos para operar e consertar a coisa quando ela quebra. Para um fundador não-técnico, documentação não é papelada para engenheiros. É o ativo que transforma a sua base de código de uma caixa-preta que você aluga em algo que você de fato possui. Boa documentação significa que o próximo desenvolvedor assume o seu sistema em dias. Documentação ruim ou ausente significa que toda pessoa que um dia tocar no seu código te deixa numa posição frágil.
Por que isso importa mais para você do que para os engenheiros
Engenheiros debatem documentação como uma questão de ofício. Para você é uma questão de controle. Todo sistema não documentado tem exatamente uma saída: a cabeça de quem o construiu. Quando essa pessoa sai, adoece ou simplesmente esquece, o conhecimento vai junto. Esse é o problema do bus factor, e a documentação é o seu seguro mais barato.
É também a forma silenciosa de lock-in. Já escrevemos sobre como o vendor lock-in é um preço que você paga por ficar. Código não documentado é a mesma armadilha vestindo outra roupa. Você não está preso a uma plataforma; está preso a uma pessoa ou a uma software house, porque só eles conseguem decifrar o que existe. No dia em que você quiser uma segunda opinião, um novo time ou um orçamento justo para estender o produto, a ausência de documentação é o que torna a saída cara.
Nada disso exige que você leia uma linha de código. Exige que você saiba quais documentos deveriam existir e insista que existam.
Os documentos que um fundador deveria de fato exigir
Peça a um engenheiro “os quatro tipos de documentação” e você vai receber uma taxonomia que serve a quem escreve documentação para viver. Aqui vai a versão que serve a quem paga a conta da construção. Cinco documentos cobrem quase tudo o que importa.
O guia de configuração, ou README. Como um novo desenvolvedor coloca o sistema para rodar na própria máquina, do começo ao fim. Se um desenvolvedor competente não consegue ir do zero a uma cópia local funcionando seguindo esse único arquivo, ele está incompleto. Este é o documento mais valioso, e o que mais falta.
A visão geral da arquitetura. Um mapa curto e em linguagem simples das partes principais e de como elas conversam. Quais são os blocos principais, onde os dados ficam, o que acontece quando um usuário faz a ação central. Duas ou três páginas e um diagrama. É o que permite a um novo desenvolvedor, ou a um CTO fracionário que você traga, entender o seu sistema sem ler tudo antes.
Documentação de integrações e de API. Como o seu sistema se conecta ao mundo externo e como as próprias partes se conectam entre si. De quais terceiros você depende, o que quebra se um deles mudar, onde ficam as chaves e credenciais (as referências, não os segredos em si). É o mapa das suas dependências, e é nas dependências que as surpresas se escondem.
Runbooks de operação. O que fazer quando algo dá errado às 2 da manhã. Como fazer o deploy de uma mudança, como restaurar a partir de um backup, como saber se o sistema está saudável. É a diferença entre um incidente que dura vinte minutos e um que dura um fim de semana.
Registros de decisão. Notas curtas sobre por que as escolhas não óbvias foram feitas. Por que este banco de dados, por que este provedor de pagamento, por que a gambiarra estranha no checkout. Sem elas, o próximo desenvolvedor vai “limpar” algo estrutural e quebrar, porque ninguém escreveu que aquilo estava ali de propósito.
Você não precisa que os cinco sejam longos. Precisa que existam e estejam atualizados. Um README de uma página que funciona vale mais que um manual de cinquenta páginas que ninguém atualizou desde a primeira versão.
Quanta documentação de software é suficiente
O instinto, depois que um fundador se queima, é exigir documentação de tudo. Esse é um erro por si só. Documentação é código que precisa ser mantido, e documentar demais um produto novo que ainda muda toda semana é um custo real com prazo de validade curto. Você vai pagar para escrever páginas que descrevem features que apaga no mês seguinte.
O teste honesto é uma única pergunta: um desenvolvedor competente que nunca viu este sistema conseguiria entregar uma mudança pequena e segura na primeira semana, usando só o material escrito e sem acesso a quem o construiu? Se sim, a sua documentação é suficiente para o estágio. Se não, você tem uma lacuna, e ela é tão cara quanto a última seção descreveu.
Protótipos descartáveis mal precisam de docs, porque você planeja descartá-los. No instante em que o código vai para produção e um cliente real depende dele, a conta se inverte. Essa é a linha. Antes dela, mantenha notas. Depois dela, exija os cinco documentos.
Como distinguir boa documentação de teatro
Você não lê o código, então não consegue avaliar os docs diretamente. Ainda assim, dá para testá-los, e o teste é barato. Quando você traz um novo desenvolvedor ou avalia uma empresa de desenvolvimento de software, entregue a sua documentação e a sua base de código e pergunte em quanto tempo a pessoa conseguiria fazer uma mudança pequena com segurança. Uma resposta confiante e específica, que cita o seu guia de configuração de verdade, é bom sinal. Vagueza, ou um pedido para “só marcar uma call com o desenvolvedor original”, te diz que a documentação não está fazendo o trabalho dela.
O outro indício é a atualidade. Abra o guia de configuração e compare a última vez que ele mudou com a última vez que o código mudou. Documentação que não é tocada há seis meses enquanto o produto foi entregue toda semana é decoração, não documentação. Docs de verdade são atualizados no mesmo fôlego do código que descrevem. Peça a quem constrói para você tratar uma atualização de documentação como parte do “pronto”, não como um favor que fará depois.
A Write the Docs, a comunidade de profissionais de documentação, resume o objetivo de forma simples: a documentação deve permitir que os leitores “tenham sucesso por conta própria”. Se os seus docs não deixam uma pessoa nova ter sucesso sem um tour guiado, eles não estão prontos.
Quem escreve, e quanto deveria custar
Quem escreve a documentação são as pessoas que constroem o seu software. Não um redator técnico à parte, não você, e não um estagiário trazido no fim para “documentar o que existe”. O desenvolvedor que tomou uma decisão é o único que consegue explicá-la de forma barata, e só consegue enquanto ela está fresca. Uma semana depois já meio esqueceu; um mês depois está chutando como todo mundo.
Por isso a documentação deveria te custar quase nada como item de linha. Um time competente a escreve como subproduto da construção, dentro das mesmas horas. Quando uma software house cota documentação como uma fase separada e cara no fim, leia como um alerta: normalmente significa que ela não documenta enquanto constrói, o que significa que o resto do trabalho tem a mesma qualidade feita depois. O custo certo de boa documentação é um imposto pequeno pago continuamente, nunca uma conta grande paga de uma vez no fim.
Coloque no contrato, não na esperança
O jeito confiável de conseguir documentação é exigi-la antes de o trabalho começar, não pedi-la depois. Quando você fecha um escopo com um desenvolvedor ou uma software house, nomeie as entregas. Um produto funcionando e os cinco documentos acima. Faça de “documentação atualizada” parte do que “terminado” significa em cada marco, do mesmo jeito que você definiria qualquer outro critério de aceite em um escopo de trabalho.
Isso não te custa nada a mais se você disser desde o início, porque um time competente documenta enquanto trabalha. Custa uma fortuna se você pedir no fim, porque reconstruir o raciocínio por trás de seis meses de decisões depois do fato é lento, mal recebido e muitas vezes apenas adivinhado. Os fundadores que nunca se queimam com um desenvolvedor que sai são os que fizeram do mapa uma condição da construção, não uma esperança para depois.
Documentação é a linha menos glamourosa de qualquer projeto de software e a que decide, mais do que quase qualquer outra coisa, se aquilo que você pagou é um ativo que você possui ou um passivo que você aluga. Exija o mapa. Você pagou pelo território.
Perguntas frequentes
O que significa documentação de software?
É o registro escrito de como um sistema de software é construído, operado e mantido: instruções de configuração, um mapa de como as partes se conectam, notas sobre por que decisões-chave foram tomadas e passos para operar e consertar. Para um fundador não-técnico, é o que permite a um novo desenvolvedor assumir o sistema sem depender de quem o construiu originalmente.
Qual é um exemplo de documentação de software?
O exemplo mais comum e útil é um README: um único arquivo que diz a um novo desenvolvedor exatamente como colocar o sistema para rodar na própria máquina, passo a passo. Outros exemplos são uma visão geral da arquitetura (um mapa em linguagem simples das partes principais), docs de integração (como se conecta a terceiros), runbooks de operação (o que fazer quando algo quebra) e registros de decisão (por que escolhas não óbvias foram feitas).
Quais são os quatro tipos de documentação?
Engenheiros costumam citar tipos como tutoriais, guias práticos, referência e explicação. A versão que importa para um fundador que paga pela construção são cinco documentos: um guia de configuração (README), uma visão geral da arquitetura, docs de integração e de API, runbooks de operação e registros de decisão. Eles cobrem o conhecimento que, de outra forma, viveria só na cabeça de um desenvolvedor.
De quanta documentação uma startup pequena precisa?
O suficiente para que um desenvolvedor competente que nunca viu o sistema consiga entregar uma mudança pequena e segura na primeira semana usando só o material escrito. Abaixo dessa barra você tem um risco; acima dela, provavelmente está documentando demais um produto que ainda muda. Protótipos descartáveis mal precisam de docs; qualquer coisa da qual um cliente pagante dependa precisa do conjunto essencial.
Qual software tem a melhor documentação?
Essa é uma pergunta de ferramenta, e é a errada para um fundador. A qualidade da sua documentação depende da disciplina de quem a escreve, não da ferramenta em que ela vive. Um README atual e claro em um wiki simples vale mais que uma plataforma de documentação sofisticada cheia de páginas desatualizadas. Julgue o hábito, não o software.
Como garanto que o meu desenvolvedor realmente documente?
Exija antes de o trabalho começar. Nomeie os documentos como entregas no seu escopo de trabalho e faça de “documentação atualizada” parte do que “terminado” significa em cada marco. Um time competente documenta enquanto constrói, a quase nenhum custo extra. Pedir só no fim é quando a documentação fica cara, mal recebida e pouco confiável.