Porque é um esforço extra para criar e manter esse documento, e muitas pessoas não entendem os benefícios associados.
Muitos programadores não são bons escritores técnicos (embora muitos sejam); eles raramente escrevem documentos estritamente para consumo humano, portanto eles não têm prática e não gostam de fazer isso. Escrever uma visão geral do código leva tempo que você não pode gastar em codificação, e o benefício inicial para um projeto é sempre maior se você puder dizer "Apoiamos todas as três variantes de codificação" em vez de "Nós realmente explicações claras do nosso código! " A noção de que tal documento atrairá mais desenvolvedores para que, a longo prazo, mais código seja escrito não seja exatamente estranho para eles, mas é percebido como uma aposta incerta; Esse texto realmente fará a diferença entre conseguir um colaborador ou não? Se eu continuar codificando agora , certamente faremos isso.
Um documento de visão geral de código também pode fazer com que as pessoas se sintam defensivas; é difícil descrever decisões de nível mais alto sem sentir a necessidade de justificá-las, e com muita frequência as pessoas tomam decisões sem uma razão que "soa boa o suficiente" quando escritas de fato. Há também um efeito relacionado ao já mencionado: uma vez que a atualização do texto para se adequar ao código em mudança causa um esforço adicional, isso pode desencorajar mudanças radicais no código. Às vezes, essa estabilidade é uma coisa boa, mas se o código realmente precisar de uma reescrita de nível médio, isso se transformará em um risco.