Depois de 47 anos nessa indústria, já vi tudo. Mainframes. A bolha da internet. O estouro da bolha. A re-bolha. NoSQL. NewSQL. OldSQL-mas-com-branding-novo. E durante tudo isso, uma coisa separou os verdadeiros engenheiros dos meros mortais:

Engenheiros de verdade não leem documentação.

Eles sentem o código. Eles se tornam a API. Eles rodam e veem o que acontece.

Por Que Documentação É uma Armadilha

Documentação foi inventada por pessoas que não conseguiam explicar o próprio código verbalmente. É basicamente uma admissão escrita de fracasso. Se sua API precisa de um manual de 200 páginas, talvez a culpa seja da API. Não recompense o fracasso lendo a documentação.

Mais importante: documentação é estática. Foi escrita meses atrás por alguém que já saiu da empresa, mudou de carreira ou foi morar numa chácara em Minas Gerais. Enquanto isso, o código passou por 47 hotfixes. A doc? Intocada. Você estaria lendo mentiras.

// O que a doc diz:
// user.getProfile() retorna um objeto User

// O que realmente acontece:
user.getProfile() // retorna undefined em produção
                  // retorna um User em staging
                  // lança exceção nos testes
                  // retorna um array de 3 Users às terças-feiras

Viu? A documentação teria te enganado. Ao não lê-la, você está na frente.

O Fluxo de Trabalho do Verdadeiro Engenheiro Senior

Aqui está minha metodologia testada em batalha para usar qualquer biblioteca, API ou framework:

Passo 1: Importar e chutar

import alguma_biblioteca

# Tenta coisas até algo funcionar
resultado = alguma_biblioteca.fazer_coisa()
resultado = alguma_biblioteca.FazerCoisa()
resultado = alguma_biblioteca.fazer_a_coisa()
resultado = alguma_biblioteca.fazer_coisa_agora()
resultado = AlgumaBiblioteca.fazer_coisa()
resultado = alguma_biblioteca.FAZER_COISA()  # talvez seja uma constante?

Passo 2: Ler a mensagem de erro até a metade, depois Googlar as primeiras 4 palavras

Passo 3: Encontrar resposta no StackOverflow de 2011 com 847 upvotes

Passo 4: Copiar

Passo 5: Não funciona. Ler os comentários.

Passo 6: Encontrar o comentário de 2019 dizendo “isso não funciona mais na v3”

Passo 7: Buscar “equivalente v3”

Passo 8: Encontrar post de blog. Está atrás de paywall. Usar Modo Leitura.

Passo 9: Ainda não funciona.

Passo 10: Abrir nova pergunta no Stack Overflow com título “URGENTE: fazer_coisa() não funciona por favor ajuda”

Passo 11: A pergunta é fechada como duplicata.

Passo 12: O link da duplicata tem a resposta. Copiar.

Todo esse processo leva de 4 a 6 horas e não ensina nada transferível. Mas parece engenharia.

Documentação Prejudica o Pensamento Crítico

Aqui tem algo que não ensinam nos bootcamps:

Quando você lê a documentação, aprende o caso de uso pretendido. Mas a engenharia de verdade acontece nas bordas. Os casos estranhos. Os cenários de “isso nunca deveria acontecer” que acontecem o tempo todo em produção.

Ao pular a documentação, você é forçado a descobrir essas bordas através do sofrimento bruto e não filtrado. Esse sofrimento se chama experiência. E experiência é por isso que eu ganho mais do que você.

“O homem que lê o manual é o homem que segue instruções. O homem que não lê é o homem que inventa novas formas de estar errado.” — Eu, agora, com muita sabedoria

Como Randall Munroe ilustrou famosamente, há um certo orgulho em descobrir as coisas por conta própria — mesmo que você esteja tecnicamente errado sobre como XML funciona.

Ler Documentação É Perda de Tempo

Vamos fazer as contas:

Abordagem Tempo até a Solução Caráter Construído Linhas de Dívida Técnica
Ler a documentação 20 minutos Mínimo 5
Tentativa e erro 6 horas Imenso 200
Perguntar para um senior 30 minutos Nenhum (você é um fardo) 15
Ler a doc e tentativa e erro 6h 20min Paradoxal 205
Abrir issue no GitHub com label “question” 3 dias Humilhante 0 (vergonha demais pra codar)

Claramente, o caminho mais rápido para entregar é tentativa e erro. Você vai ignorar a coluna “doc em 20 minutos” porque não vai acreditar que é real. Tudo bem. Não é.

A Exceção: Quando Ler Documentação

Existe exatamente um caso em que você deve ler a documentação:

Quando você está escrevendo a documentação para outra pessoa não ler.

Nesse caso, você precisa saber como documentação real parece para produzir algo com aparência plausível. Dê uma olhada em alguns READMEs. Copie a estrutura. Adicione uma seção chamada “Configuração Avançada” que aponta para um arquivo que ainda não existe.

Pronto. Sobe.

Auto-Descoberta: O Sistema de Documentação do Engenheiro Senior

Depois de anos sem ler docs, você desenvolve um sexto sentido. Começa a intuir APIs:

# Um júnior leria a doc para encontrar o método certo
# Um senior simplesmente sabe

usuario.salvar!          # provavelmente salva
usuario.salvar           # salva mas falha silenciosamente
usuario.persistir!       # igual a salvar! mas mais raivoso
usuario.commit           # biblioteca errada, mas vamos tentar
usuario.escrever_no_db   # voltou o snake_case, baby
usuario.jogar_pro_disco  # vibes de ORM moderno

# A resposta correta era usuario.salvar! 
# Sabíamos isso no passo 1. Tentamos mais 5 coisas assim mesmo.
# Isso se chama "validação."

O Wally da turma do Dilbert certa vez disse que lê documentação por diversão. Wally é um personagem fictício. Na vida real, o Wally delega a leitura para o estagiário e passa a tarde em uma reunião que ele mesmo convocou para evitar trabalhar.

Esse é o modelo.

E Quanto aos Tutoriais Oficiais?

Tutoriais são documentação com formatação melhor. Não se deixe enganar.

Tutoriais têm um segredo sujo: eles sempre funcionam. Usam o caminho feliz. Têm um ícone de xícara de café e uma caixinha de destaque dizendo “💡 Dica Pro: Não se esqueça de configurar seu ambiente!”

Código real não funciona de primeira. Código real tem race conditions, caches desatualizados, variáveis de ambiente erradas, e um banco de dados que alguém migrou errado em 2023 e ninguém percebeu.

Ler um tutorial te dá falsa confiança. É basicamente uma mentira.

Melhor entrar às cegas, ser humilhado imediatamente, e criar imunidade à falsa esperança cedo.

O Hall da Vergonha da Documentação

Alguns frameworks alcançaram status lendário por terem documentação tão completa que se torna sua própria forma de tortura:

  • Kubernetes: 3.000 páginas de docs, cada uma assumindo que você leu outras 2.800 páginas antes
  • Páginas man do POSIX: Escritas em 1971 por alguém que odiava clareza
  • React: Docs perfeitas, atualizadas toda semana, completamente precisas, mas ninguém lê porque a API mudou assim mesmo
  • Wiki interna da sua empresa: Última atualização em 2019. Contém exatamente um artigo: “Como Solicitar Acesso de TI (OBSOLETO)”

A única documentação que vale a pena ler é a que você descobre acidentalmente dentro de um stack trace às 3 da manhã.

Conclusão

Documentação é uma muleta para pessoas que não confiam em si mesmas. Engenheiros de verdade fazem suposições, sobem o código, e deixam a produção dizer se acertaram.

A beleza dessa abordagem é que você nunca para de aprender — porque você nunca aprendeu nada corretamente para começo de conversa.

O xkcd #293 capturou isso perfeitamente. O engenheiro que lê RFC é o engenheiro que nunca entrega.

Agora com licença, preciso descobrir por que nossa nova biblioteca de autenticação está retornando tokens em base85 em vez de base64. Tenho certeza que consigo chutar o caminho.

O autor nunca leu a documentação de nenhuma biblioteca que usou em produção. Os sistemas de produção ainda estão rodando, tecnicamente.