Documentacao nao e luxo: como manter conhecimento vivo na engenharia

Quando o README te deixa na mao

Ja aconteceu de voce clonar um projeto e travar logo no comeco?

Teve uma madrugada daquelas em que voce ja deveria estar dormindo que eu passei quase duas horas tentando subir um ambiente local.

Nada fora do comum:

• um backend
• banco de dados
• fila
• cache

O problema nao era tecnico.

Era o README.

As instrucoes eram basicamente:

“Instale as dependencias e rode.”

Mas rode o que?

• Qual comando exatamente?
• Qual versao das ferramentas?
• Em que ordem os servicos sobem?

Sem essas respostas, o processo vira tentativa e erro.

Voce comeca a testar coisas, abrir arquivos, procurar pistas no codigo… ate que, eventualmente, funciona.

Mas a sensacao que fica e ruim.

Nao pelo esforco tecnico isso faz parte mas pelo tempo desperdicado em algo que poderia ser simples.

E ai vem a pior parte:

Voce resolve… mas sabe que a proxima pessoa provavelmente vai passar pelo mesmo caminho.

O problema real

Se voce olhar com calma, o problema raramente comeca na falta de documentacao.

Ele comeca na forma como ela e criada.

Em muitos times de engenharia, a documentacao nasce no susto:

• no meio de uma entrega urgente
• durante um incidente
• perto de um release apertado

Ela resolve um problema imediato e depois e esquecida.

Com o tempo, vira um acervo estatico.

As vezes ate bem escrito.

Mas desatualizado.

Sem contexto.

Dificil de confiar.

E como entrar em um museu: interessante de olhar, mas pouco util na pratica.

Voce ate encontra informacoes, mas nao sabe se ainda sao validas.

E isso e mais comum do que parece.

A falsa solucao: trocar de ferramenta

Quando a documentacao comeca a falhar, a primeira reacao costuma ser culpar a ferramenta.

“Vamos migrar pro Notion” “A gente precisa de um portal interno melhor”

Isso cria uma sensacao de evolucao.

Como se reorganizar o espaco fosse, por si so, resolver o problema.

Mas, na pratica, quase nunca resolve.

Trocar de ferramenta sem mudar o comportamento so muda o endereco do problema.

Eu mesmo ja passei por isso: migracao, reestruturacao, tudo mais organizado e, em pouco tempo, a documentacao estava desatualizada de novo.

O problema de verdade: falta de habito

No fim, a questao central nao e onde a documentacao esta.

E como ela e tratada no dia a dia.

Sem um minimo de disciplina no processo:

• ninguem se sente responsavel por atualizar
• ninguem revisa com frequencia
• ninguem confia totalmente no que esta escrito

E quando a confianca some, a documentacao deixa de ser usada.

Nesse ponto, nao importa a ferramenta.

Ela vira apenas mais uma aba aberta ignorada na pratica.

Docs como codigo: o que funcionou pra mim

Lembro de um time que eu trabalhei onde a gente comecou simples. Quase primitivo, pra ser sincero.

Markdown no repositorio.

Nada de plataforma magica. Nada de ferramenta cara.

So texto, junto do codigo, do jeito que dava.

Arquivo de decisao arquitetural, guia de setup local, runbook de incidente.

Tudo versionado junto com o codigo.

E isso mudou o jogo.

Porque quando a doc ta no mesmo fluxo do codigo, ela entra no dia a dia.

Virou regra: PR que muda comportamento importante, muda documentacao tambem.

As vezes era uma linha.

As vezes era uma secao inteira.

Mas passava por review igual.

Com o tempo, a gente adicionou validacao de links no CI pra evitar doc quebrada.

Coisa simples.

Nada mirabolante.

E ja evitava aquele classico “clica no link” -> 404.

Documentacao perfeita e igual unicornio: todo mundo quer ver, quase ninguem encontra.

Mas documentacao util, atualizada o suficiente e facil de achar?

Isso da pra ter.

O desafio da manutencao (o mais dificil)

Aqui mora a parte espinhosa.

Escrever doc uma vez e relativamente facil.

Manter viva e que pega.

Porque manutencao de doc nao grita.

Nao quebra build.

Nao dispara alerta as 3h da manha.

Ela so cobra a conta depois, em silencio.

No onboarding lento.

No deploy inseguro.

Na dependencia eterna de “fulano sabe”.

O que funcionou melhor nos times em que eu passei foi combinar poucas regras claras.

Quem abriu PR e mudou fluxo, atualiza a doc no mesmo PR.

A cada ciclo, alguem revisa paginas mais criticas: setup local, deploy, incidentes e arquitetura.

Quando ninguem mexe numa doc por meses, a gente marca como “precisa revisar” em vez de fingir que ta tudo certo.

Nao e glamour.

E disciplina.

E, sendo honesto, tem semana que escorrega. Tem sprint que a gente olha e pensa “puts, essa secao aqui ja era”.

Mas ai a gente volta, ajusta, segue.

O que vale a pena documentar (e o que nao)

Se voce estiver na duvida do que priorizar, eu iria no que doi quando falta.

Vou te dar uma ideia do que eu priorizo hoje:

Como rodar o projeto local sem adivinhacao. Esse e o minimo. Se a pessoa nova nao conseguir subir em 15 minutos, a gente falhou.

Como fazer deploy sem ritual secreto. Sabe aquele passo que “so o Joao sabe”? Se nao ta escrito, nao existe.

Como agir quando der incidente. Porque na hora do susto, ninguem quer ficar cacando informacao.

Decisoes importantes de arquitetura e o porque delas. Isso aqui evita que o time fique refazendo a mesma discussao seis meses depois.

Integracoes sensiveis com outros sistemas. O que esperar, o que pode quebrar, quem avisar.

Agora, o que eu evito?

Comentario obvio.

Ninguem precisa de ”// soma dois numeros”.

Ninguem precisa de wiki gigante explicando coisa que o codigo ja deixa claro.

Documentar nao e duplicar tudo.

E registrar contexto que some da cabeca com o tempo.

Pra fechar

Hoje eu vejo documentacao como um ato de empatia.

E alguem no presente ajudando alguem no futuro.

As vezes esse alguem e voce mesmo, seis meses depois, tentando lembrar por que tomou uma decisao.

Quando a gente documenta bem, a gente respeita o tempo do outro.

E respeita o proprio tempo tambem.

No seu time, a documentacao ajuda ou atrapalha?

Fala serio ja passei pelos dois lados. E hoje eu sei que prefiro um time que documenta mal, mas mantem, do que um time que fez a documentacao perfeita uma vez e abandonou.

Se quiser, responde ai nos comentarios. Quero saber como voces lidam com isso.