Escrever documentações é difícil?

Eu não diria que é difícil. Diria que é chato, e subvalorizado.
As pessoas focam em entregar a solução deixam a documentação para o último passo e apenas em caso de sentir falta dela.
Aí vc tem um sistema inteiro pronto, cheio de detalhes para explicar aos interessados, faz as pressas, não lembra de tudo, teria que ler cada linha de código pra não deixar passar nada...
É um trabalho chato, que parece não gerar muito valor qnd vc tem uma aplicação para especificar para o desenvolvedor e o desenvolvedor tem que codar. Documentar para o usuário fica em último plano.

Cara, eu ia usar um sistema no meu SaaS e pela doc tão ruim, fui para um concorrente que é até mais caro
agora mesmo tou apanhando com uma outra documentação nesse exato momento.

Junto tou escrevendo uma para meu sistema, tou escrevendo com ajuda do ChatGPT, entrego pra ele o endpoint, explico o que faz, inputs e output e peço ajuda dele para explicar isso como se fosse para uma pessoa não técnica, isso tem me ajudado bastante eu ter mais clareza na documentação.

Também entrego testes unitários para ele ter ainda mais contexto sobre a rota.

Logo mais vou começar a melhorar a doc de um parceiro comercial que tenho, e vou seguir isso que tenho feito no meu.

Minha visão maninho, programar software é algo quase pessoal. A pessoa que cria uma API sempre leva consigo ao codar idioms de outras experiências, as vezes quer aplicar algo "novo" excepcionalmente nessa API, as vezes tem o próprio modus operandi a mais de 10 anos, e mesmo com erros e falhas nunca muda, e outras vezes até fica uma bagunça, um dev começa bem, outro vem e implementa algo de forma não ortodoxa, um terceiro entra e muda totalmente o paradigma... são muitos fatores, mas isso falando ainda do software/API em si.

Sobre a documentação, não é difícil. Apenas é chato para algumas pessoas, e digo chato mesmo. É muito legal codar, criar as coleções no postman, integrar com um banco de dados, testes unitarios, etc. A documentação é algo que geralmente fica por ultimo, isso quando existe. Documentação de software deve ocorrer conforme o projeto evolui, ao mesmo tempo, e se possível em mais de um lugar. Uma boa API tem uma boa base teórica, quase como uma wiki, que mostra o que pode ou não ser enviado nela por exemplo, o bom e velho swagger para consultas rápidas, um dev experiênte a disposição para modificar ou dar suporte, e um ambiente de testes para ser usado durante a integração.

Já trabalhei com muitas APIs governamentais, algumas tive o prazer de encontrar um PDF perdido no site, outras tive que ir caçando as chamadas que ocorriam no site pra integrar do meu lado... essas APIs são o verdadeiro inferno. E além disso, você encontra de todo tipo: SOAP, REST, GraphQL, RPC, transferência de arquivos em rede (bancos usam esse tipo, mexi bem pouco).... Infelizmente é a nossa realidade.

Cara eu diria que depende do que você está documentando, por exemplo:

Documentação de web API:
Nesse caso basta fazer um Swagger bem parametrizado, só de colocar boas nomeclaturas nos objetos DTO, meteodos e endpoints já te deu meio caminho andando. Depois disso basta colocar alguns doc comments nas coisas que requerem uma explicação mais complexa.

Documentação/Manual de aplicações:
Esse daqui eu considero o mais chato, difícil e inútil, principalmente se ta em formato de .pdf ou PowerPoint porque qualquer mudança a doc ja fica obsoleta. Neste caso um bom UX facilita bastante porque o utilizador vai se adaptar fácil.

Documentação de projetos/bibliotecas:
Esses é o que eu mais gosto de fazer, principalmente se for numa linguagem estilo Rust que dá pra fazer doc comments realmente uteis pode dar uma olhada na documentação que fiz para o meteoritus acho que ficu bem completa.

Eu sempre tento deixar o GPT falar por mim, passo para ele o contexto da aplicação e depois peço um resumo daquilo e vou revisando, acredito que facilita muito o trabalho porque você não precisa pensar muito em como explicar o que está na sua cabeça. Também gosto de usar para ele corrigir e melhorar gramaticalmente.

A minha dica para você, que inclusive eu fiz enquanto escrevia o meteoritus é ir documentando as coisas a medida que faz, por exemplo sempre que já tiver alguma coisa estável você vai documentado aquilo, se somar isso a técnicas de clean code e nomeclatura, além de micro commits autoexplicativos você consegue facilmente passar isso para um modelo estilo chat GPT e ele vai te fazer quase 80% do trabalho pesado.

Acredito que seja questao de prioridades mesmo. Acho que a maioria das APIs nascem em ambientes que exigem agilidade para que o produto possa ser comercializado o mais rápido possível. Estou finalizando o desenvolvimento da primeira API que desenvolvi na minha carreira. No inicio, comecei documentando todos os endpoints. Mas ali pela metade do projeto, a pressão pela finalização da aplicação fez com que eu abandonasse completamente a documentação, que estava me tomando bastante tempo, diria que 20% do tempo era gasto documentando. Pretendo retomar e finalizar a documentação no futuro, mas ainda tem tantas coisas que são prioridades: correção de bugs críticos (sim, decidiram jogar pra produção antes de sequer testarmos as partes essenciais da aplicação), testes unitários, etc...

Escrever documentação é uma atividade normalmente negligenciada em muitos projetos.

Quando o backlog está grande o prazo está curto, normalmente a documentação é uma das primeiras coisas que é cortada do projeto.

Além do mais, muitas pessoas acham que instalar o Swagger é documentar uma API.