Documentação viva: o que manter perto do código

README, runbooks e diagramas como código — priorizar o que muda com o sistema e evitar wikis que mentem desde o segundo mês.

Contexto

Este artigo integra a série Governança & práticas no blog da Barre — pensado para CTOs, arquitetos e líderes de produto que precisam de decisões com critério e continuidade operacional, não de modismos.

Pressão de negócio e restrições

Documentação viva ganha relevância quando o custo de ambiguidade (atrasos, retrabalho, incidentes evitáveis) ultrapassa o custo de manter decisões explícitas e próximas do código.

Relacionado com o foco anunciado no título: README, runbooks e diagramas como código — priorizar o que muda com o sistema e evitar wikis que mentem desde o segundo mês.

Restrições típicas: tempo de equipa, legado heterogéneo, pressão por entrega contínua — por isso o desenho tem de ser mínimo mas honesto: poucas regras, bem escolhidas, com dono.

Padrões que voltam a aparecer

• Excepções não registadas — cada uma corroê o padrão sem rasto.

• Regras sem dono ou sem revisão na cadência de mudança — ficam obsoletas em semanas.

• Documentação ou comités que impressionam mas não são usados em incidente ou release.

Decisão em uma frase, aplicada

Decisão útil: trocar volume de páginas por critério de pronto: sem atualização rastreável, não há release — ou há excepção registada.

Isto não substitui julgamento humano; reduz improviso quando a pressão sobe.

Consequências, trade-offs e o que vigilar

Aceitar menos ornamento e mais ligação causal ao sistema em mudança implica dizer não a iniciativas que não atualizam o artefacto na mesma onda que o código.

Trade-offs: velocidade percebida pode baixar no curto prazo; ganho é menos incidente e onboarding mais rápido.

O que vigilar

• Taxa de divergência entre doc e comportamento real em fluxos críticos.

• Tempo médio até um novo membro encontrar resposta útil sem «tradutor».

• Excepções ao padrão: quantidade e tempo em aberto.

Próximos passos (se for prioridade agora)

1. Escolher um fluxo crítico e publicar desenho no mesmo sítio onde o trabalho acontece (repo / diagrama como código), com dono.

2. Definir revisão na cadência de release ou mensal — o que está obsoleto fica listado como risco, não como «pendência».

3. Limitar excepções ao padrão: registo curto (quem, até quando, compensação).

Síntese

Documentação viva resume-se a isto: menos ambiguidade, mais decisão repetível — o resto são ferramentas ao serviço desse critério.

---

Resumo: README, runbooks e diagramas como código — priorizar o que muda com o sistema e evitar wikis que mentem desde o segundo mês.