Documentação técnica que o time lê: ferramentas, formatos e cultura

1. Por que a documentação técnica falha (e como evitar)

O mito da documentação "completa"

Muitos times acreditam que documentação técnica ideal é aquela que cobre cada detalhe do sistema. Na prática, documentação "completa" vira rapidamente um peso morto. Cada funcionalidade nova exige atualização em múltiplos lugares, e o custo de manutenção supera o valor gerado. O resultado? Documentos enormes, desatualizados e que ninguém lê.

A abordagem correta é documentar o mínimo necessário para que o time seja produtivo. Pergunte-se: "Se esse documento sumisse amanhã, o time sofreria?" Se a resposta for não, talvez ele não precise existir.

Documentação desatualizada como débito técnico invisível

Documentação desatualizada é pior que nenhuma documentação. Ela engana novos membros do time, gera retrabalho e cria dependência em pessoas específicas que "sabem como realmente funciona". O impacto no onboarding é devastador: um desenvolvedor júnior pode perder dias seguindo instruções incorretas.

Falta de público-alvo

Misturar instruções para iniciantes com detalhes para especialistas no mesmo documento é receita para confusão. Um README não deve tentar agradar todo mundo. Separe claramente:
- Quickstart: para quem quer rodar o projeto em 5 minutos
- Guia de contribuição: para quem vai modificar o código
- Referência técnica: para consultas específicas

2. Formatos que funcionam na prática

README como porta de entrada

Um README eficaz segue a estrutura mínima viável:

# Nome do Projeto

## O que é
Breve descrição do propósito (2-3 frases).

## Por que existe
Contexto da decisão de criar este projeto.

## Como começar
1. Pré-requisitos (versões de linguagem, ferramentas)
2. Passos para instalação
3. Comando para rodar localmente

## Exemplo rápido
Código funcional mínimo que demonstra o uso principal.

ADRs (Architecture Decision Records)

ADRs documentam decisões técnicas importantes com um formato conciso:

# ADR-001: Escolha do banco de dados PostgreSQL

## Contexto
Precisamos de um banco relacional com suporte a transações ACID para o módulo financeiro.

## Decisão
Utilizaremos PostgreSQL 15 devido a:
- Maturidade do ecossistema
- Suporte nativo a JSON para dados semiestruturados
- Performance comprovada em operações concorrentes

## Consequências
Positivas: comunidade grande, ferramentas maduras, ORMs compatíveis.
Negativas: custo de infraestrutura maior que SQLite, necessidade de DBA dedicado.

Documentação viva (living docs)

Documentação gerada a partir do código reduz drasticamente a desatualização. Exemplos práticos:

OpenAPI para APIs REST:

openapi: 3.0.0
info:
  title: API de Pagamentos
  version: 1.0.0
paths:
  /payments:
    post:
      summary: Criar novo pagamento
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  description: Valor em centavos
                currency:
                  type: string
                  enum: [BRL, USD]
      responses:
        '201':
          description: Pagamento criado com sucesso

Mermaid para diagramas:

graph TD
    A[Cliente] -->|Requisição HTTP| B[API Gateway]
    B --> C[Serviço de Autenticação]
    B --> D[Serviço de Pagamentos]
    D --> E[(Banco de Dados)]
    D --> F[API de Terceiros]

3. Ferramentas essenciais para o ecossistema de docs

Plataformas de documentação

  • MkDocs: Ideal para documentação estática com Markdown. Rápido, simples e com tema Material que fica profissional. Use quando o time quer docs no próprio repositório.
  • Docusaurus: Mais robusto, com suporte a React e plugins. Bom para projetos open source que precisam de versões múltiplas da documentação.
  • GitBook: Interface WYSIWYG, bom para times não-técnicos que precisam colaborar. Cuidado com vendor lock-in.

Versionamento de documentação junto com o código

Manter docs no mesmo repositório do código (monorepo de docs) garante que:
- Pull requests atualizem código e documentação simultaneamente
- Tags de versão correspondam a snapshots da documentação
- CI/CD publique automaticamente (GitHub Pages, Read the Docs)

Ferramentas de diagramação como código

Diagramas mantidos como código evitam o problema de "quem tem o arquivo .drawio original?":

PlantUML:

@startuml
actor Usuário
participant "API" as API
database "DB" as DB

Usuário -> API: POST /login
API -> DB: SELECT * FROM users WHERE email=?
DB --> API: user data
API --> Usuário: JWT token
@enduml

Graphviz:

digraph G {
    rankdir=LR;
    node [shape=box];
    "Input" -> "Processador" -> "Output";
    "Processador" -> "Cache" [style=dashed];
}

4. Cultura de documentação: o fator humano

Documentação como parte da definição de pronto (DoD)

Estabeleça critérios objetivos:
- README atualizado com novas variáveis de ambiente
- ADR criado para decisões arquiteturais
- Exemplos de código funcionais adicionados
- Changelog atualizado

Revisão de documentação no code review

Checklist mínimo para revisão:
- [ ] A documentação reflete o comportamento real do código?
- [ ] Os exemplos de código funcionam se copiados e colados?
- [ ] Há links quebrados ou referências a versões antigas?
- [ ] A linguagem é clara para o público-alvo?

Rituais de manutenção

  • Doc Days: Um dia por sprint dedicado exclusivamente a atualizar documentação
  • Responsáveis por seções: Cada módulo tem um "dono" de documentação
  • Issues de docs: Tratar documentação desatualizada como bug legítimo no backlog

5. Formatos específicos para diferentes públicos

Documentação de API

Além do OpenAPI, inclua exemplos interativos:

## Exemplo de requisição

curl -X POST https://api.exemplo.com/v1/payments \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "currency": "BRL",
    "description": "Pedido #12345"
  }'

## Resposta esperada

{
  "id": "pay_abc123",
  "status": "processing",
  "amount": 1500,
  "created_at": "2024-01-15T10:30:00Z"
}

Runbooks e troubleshooting

Formato passo-a-passo para situações reais:

## Problema: Serviço X não responde

### Sintomas
- Health check retorna 503
- Logs mostram "connection refused" na porta 8080

### Causa provável
Processo do serviço foi encerrado por OOM killer

### Resolução
1. Verificar status do processo:
   systemctl status servico-x

2. Se inativo, reiniciar:
   systemctl start servico-x

3. Verificar logs após reinício:
   journalctl -u servico-x --since "5 minutes ago"

4. Se falhar novamente, aumentar limite de memória:
   vim /etc/systemd/system/servico-x.service
   # Adicionar: MemoryLimit=512M

Documentação de arquitetura com C4 model

## Diagrama de Contexto (Nível 1)

Sistema de Pagamentos se comunica com:
- Gateway de Pagamento externo
- Sistema de Contabilidade
- Notificações por email

## Diagrama de Containers (Nível 2)

- Web App (React) -> API Gateway (Node.js)
- API Gateway -> Serviço de Pagamentos (Go)
- Serviço de Pagamentos -> PostgreSQL
- Serviço de Pagamentos -> Redis (cache)

6. Métricas para saber se a documentação é lida

Métricas de engajamento

Ferramentas como Plausible ou Matomo podem ser embutidas em docs estáticas para medir:
- Termos de busca mais frequentes (indicam o que falta documentar)
- Páginas com maior taxa de abandono (precisam de revisão)
- Documentos mais acessados (prioridade de manutenção)

Feedback loop integrado

Adicione ao final de cada página:

---
**Esta documentação foi útil?** 👍 👎

**Encontrou um erro?** [Abra uma issue](https://github.com/time/docs/issues/new)

Correlação com redução de perguntas repetidas

Configure alertas no Slack para quando a mesma pergunta for feita 3 vezes na semana. Isso indica um gap na documentação. Monitore a redução dessas perguntas após atualizar os docs relevantes.

Referências