Por que tantas bibliotecas não possuem documentação ruim? [fechadas]

De maneira semelhante à Como os projetos de código aberto podem ser bem-sucedidos sem documentação sobre seu design ou arquitetura? pergunta, estou curioso: por que tantas bibliotecas estão faltando na documentação do usuário final?

Minha opinião é esta:

1. Quase todo mundo concorda que ler o código fonte é mais difícil do que escrever o código fonte.
2. Sem documentação, é preciso ler o código-fonte da biblioteca para poder usá-la.
3. Portanto, usar a biblioteca não documentada é mais trabalhoso do que apenas recriar a biblioteca do zero.
4. Como resultado, se você quiser que as pessoas usem sua biblioteca, é melhor garantir que ela esteja documentada.

Sei que muitos desenvolvedores não gostam de escrever documentos e concordo que pode ser um trabalho tedioso. Mas é um trabalho essencial. Eu diria até que é mais importante que uma biblioteca tenha boa documentação do que a melhor interface de programador do mundo. (As pessoas usam bibliotecas de merda o tempo todo; poucas usam bibliotecas não documentadas)

Oh, note que quando digo documentação, quero dizer documentação real. Não é o clichê Sandcastle / Javadoc / Doxygen.

Acho que você já respondeu à sua própria pergunta: na maioria dos casos, os desenvolvedores simplesmente não se incomodam. O problema é especialmente prevalente em projetos voluntários.

Eu acho que há outro problema importante: em muitos casos, os desenvolvedores realmente não desenvolveram um modelo geral de como sua biblioteca funciona (ou apenas têm dificuldade em articular esse modelo claramente). Infelizmente, articular esse modelo e como as partes do software se encaixam geralmente é a parte mais importante da documentação.

Em um caso típico, o que está escrito tem uma muito visão geral de alto nível ( "Esta é uma biblioteca para fazer coisas legais!") E, em seguida, uma descrição de nível muito baixo (tipo e descrição de cada parâmetro a ser passado para cada função). Infelizmente, raramente existe um nível intermediário sobre a teoria geral de como as coisas devem funcionar, como as peças se encaixam, etc. Muito disso remonta ao fato de que os desenvolvedores geralmente não tentaram formar, racionalizar ou entender suas idéias. código nesse nível específico de detalhe. Pelo menos em alguns casos que eu vi, os desenvolvedores que foram solicitados a escrever a documentação nesse nível a consideraram bastante problemática - a ponto de muitos quererem reescrever o código para que fosse mais organizado e mais fácil de explicar nesse nível de detalhe.

Escrever bem nesse nível de abstração é muitas vezes difícil - e se o desenvolvedor não tiver realmente pensado nisso nesse nível de abstração, muitas vezes achará o código um pouco embaraçoso e poderá reescrevê-lo antes que seja feliz sobre liberá-lo.

Às vezes, acho que é porque o desenvolvedor está tão envolvido no código que é "óbvio" para ele / ela como ele funciona e eles não conseguem entender por que não seria óbvio para mais ninguém. Da mesma forma, muitos sites de produtos dizem como o produto é maravilhoso, mas na verdade não diz o que faz!

Você apontou a resposta você mesmo:

Sei que muitos desenvolvedores não gostam de escrever documentos e concordo que pode ser um trabalho tedioso.

Como programadores, gostamos de escrever código, mas poucos de nós também gostam de escrever documentação.

Embora qualquer bom codificador conheça o valor de uma boa documentação, também leva bastante tempo para fazê-lo corretamente. Como não é agradável e leva muito tempo, ele é colocado na pilha "para fazer mais tarde", para nunca ser feito em um nível satisfatório.

Como uma observação lateral, também é muito difícil para um programador escrever documentação em seu próprio produto. Como eles conhecem o sistema tão bem, certas coisas são óbvias para eles. Essas peças geralmente nunca são mencionadas, apesar de não serem óbvias para o consumidor.

Escrever documentação é uma habilidade. Como todas as habilidades, é preciso praticar. O tempo e o esforço que gastamos escrevendo código têm um retorno imediato. Podemos ver o novo recurso, o bug corrigido, a velocidade aprimorada. Escrever documentação tem um pagamento atrasado. Ajuda a longo prazo, pois as novas pessoas precisam trabalhar no código ou se voltarmos a trabalhar no código meses ou anos depois. É natural que nos concentremos no curto prazo.

Na minha opinião, a capacidade de escrever uma boa documentação é uma das principais características que distingue grandes programadores de programadores medíocres.

A pessoa que está mais qualificada para escrever documentação também é a pessoa que tem menos motivação para fazê-lo:

ele (ou ela) é:

• principalmente um mantenedor da biblioteca, em vez de um usuário. Portanto, quanto menor e mais simples a biblioteca, mais fácil será o trabalho dele. Manter metade de um romance , além do código, apenas torna seu trabalho mais difícil,
• ele conhece a biblioteca de dentro para fora, então ele não precisa da documentação,
• ele é um programador, ele quer escrever código, não documentação.

Não consigo pensar em alguém com menos probabilidade de dizer "Hmm, eu realmente deveria passar algumas horas escrevendo documentação adequada para isso". Por que ele iria?

E, é claro, provavelmente não ajuda que exista essa lenda urbana de que comentários no estilo doxógeno gerados automaticamente são tudo o que você precisa em termos de documentação.

Portanto, mesmo nos raros casos em que um desenvolvedor está realmente disposto a escrever documentação, há 50% de chance de o desenvolvedor sofrer uma lavagem cerebral por esse culto ao pensar que tudo o que é necessário é preencher alguns desses comentários, informando sobre gemas como que "a função Foo getFoo()retorna um objeto do tipo Foo e é usada para obter o objeto Foo".

Documentação? Não precisamos de documentação fedorenta!

Sei como o código funciona, então por que gastaria algum tempo documentando meu código? Além disso, eu tenho que concluir esse projeto até sexta-feira e mal o farei como está ...