Por que engenheiros odeiam escrever documentação (e por que eles estão certos)

Se você já tentou fazer com que uma equipe de engenharia escrevesse mais documentação, sabe como funciona. Há um breve período de conformidade após o mandato, algumas páginas de wiki são criadas ou atualizadas e, em um mês, a equipe volta ao patamar anterior. A iniciativa de documentação junta-se à coleção de processos bem-intencionados que não pegaram.

A interpretação padrão da gestão é que os engenheiros são preguiçosos com a documentação ou não entendem sua importância. Essa interpretação está errada, e construir políticas com base nela produz iniciativas que falham repetidamente pelas mesmas razões estruturais.

Os engenheiros resistem à documentação porque suas objeções estão corretas.

As verdadeiras objeções

A mudança de contexto é cara. Escrever prosa e escrever código usam modos cognitivos diferentes. Mudar do pensamento lógico e rigoroso exigido para depuração ou arquitetura para o pensamento explicativo e voltado para o público exigido para a documentação é desgastante de uma forma que não aparece nas planilhas de horas. A maioria dos engenheiros relata que a mudança de contexto custa mais do que a própria escrita: os vinte minutos para voltar ao código depois de passar trinta minutos em uma página de wiki.

Parece ter baixo status. Na maioria das culturas de engenharia, entregar código tem alto status e escrever sobre código não. Ninguém é promovido por suas contribuições na wiki. A avaliação de desempenho de ninguém destaca a qualidade de seus documentos de arquitetura. A estrutura de incentivos diz aos engenheiros que a documentação é secundária em relação à construção, e eles respondem racionalmente aos incentivos.

Eles sabem que estará desatualizada em semanas. Esta é a objeção que a maioria dos gerentes ignora e que a maioria dos engenheiros sente com mais força. Um engenheiro que viu seu documento de arquitetura cuidadosamente escrito tornar-se impreciso após alguns sprints de alterações aprende que o esforço de escrever documentos tem uma meia-vida curta. A resposta racional é investir menos esforço em algo que decai rapidamente, não mais.

O público não está claro. Para quem são esses documentos? Futuros engenheiros? Colegas de equipe atuais que já conhecem o sistema? Gerentes de produto? Dependendo do público, o nível apropriado de detalhe, o enquadramento e a profundidade técnica são completamente diferentes. Sem clareza sobre o público, o engenheiro escreve no nível errado ou não escreve nada porque a ambiguidade faz com que a tarefa pareça sem limites.

Por que a motivação não é a solução

Saber que essas objeções são estruturais e não motivacionais muda a aparência da solução.

Abordagens motivacionais (mandar documentar, adicionar documentos aos requisitos do sprint, gamificar contribuições) produzem conformidade temporária, mas não abordam as razões subjacentes pelas quais os engenheiros resistem. A mudança de contexto ainda é cara, a hierarquia de status permanece inalterada e os documentos ainda ficam desatualizados.

As abordagens que realmente funcionam abordam a estrutura e não a motivação.

Remova os engenheiros do ciclo de escrita. A documentação autoescrita gera documentos estruturados a partir da atividade de engenharia que já está acontecendo: descrições de PR e mensagens de commit, conversas no Slack onde as decisões são discutidas, reuniões onde a arquitetura é debatida. A contribuição do engenheiro é o trabalho em si, e a documentação é um subproduto, em vez de uma tarefa adicional.

Faça com que os documentos permaneçam atualizados automaticamente. Quando a documentação se atualiza à medida que o código subjacente e as conversas mudam, a objeção da obsolescência desaparece. Os engenheiros estão dispostos a revisar e refinar documentos que confiam estar em grande parte corretos. Eles não estão dispostos a escrever documentos que sabem que estarão errados dentro de um mês.

Esclareça o público através do formato. Em vez de pedir aos engenheiros que escrevam para um público indefinido, forneça formatos estruturados: registros de decisão para decisões de arquitetura, documentos de integração para novos contratados, wikis de engenharia para documentação do sistema. Cada formato sugere seu público, o que torna a tarefa de escrita (ou revisão) delimitada em vez de aberta.

O modelo de revisão

O modelo de documentação mais sustentável trata os engenheiros como revisores e não como autores. O sistema gera a documentação inicial a partir das fontes disponíveis (atividade de código, conversas, reuniões). O engenheiro revisa, corrige e enriquece. A revisão é uma tarefa de dez minutos em vez de uma sessão de escrita de duas horas, a mudança de contexto é mínima e a contribuição do engenheiro é a garantia de qualidade sobre algo que já existe, em vez da criação do zero.

Este modelo respeita o tempo dos engenheiros, aborda suas objeções e produz documentos que se mantêm atualizados. Também tende a produzir uma documentação melhor do que a escrita manual, porque os documentos gerados são abrangentes (capturam tudo o que aconteceu, em vez do que o engenheiro se lembrou de anotar) e consistentes (seguem um formato padrão em vez de variar de acordo com o autor).

Perguntas frequentes

E os engenheiros que realmente gostam de escrever documentação? Eles existem e são valiosos. No modelo de revisão, eles se tornam as pessoas que enriquecem e melhoram os documentos gerados, adicionando as nuances, o contexto e a narrativa que os sistemas automatizados não conseguem produzir. Suas habilidades são melhor utilizadas no enriquecimento do que na escrita básica da qual o sistema cuida.

Os engenheiros confiarão em documentos gerados por IA? Mais facilmente do que você imagina, porque os documentos são gerados a partir de fontes que o engenheiro reconhece: seus próprios PRs, seus próprios tópicos do Slack, suas próprias discussões de reuniões. Os documentos citam essas fontes, para que o engenheiro possa verificar qualquer afirmação verificando o original. A confiança é baseada na transparência, e a geração baseada em citações a fornece.

Como lidamos com informações confidenciais ou sensíveis? O sistema deve ter limites configuráveis para o que captura. Certos canais do Slack, certos repositórios ou certas categorias de reuniões podem ser excluídos. O engenheiro controla o que o sistema vê, o que significa que informações confidenciais ficam fora dos documentos gerados.

Leitura recomendada: O custo de escrever documentos de engenharia, O paradoxo da documentação, Documentos autoescritos explicados. Páginas relacionadas: Documentos autoescritos, Para equipes de engenharia.