[taveras]

I find that many programmers are hyper-focused on writing automation for things that feel like a chore. This thinking has its purpose, but it’s almost an addiction.

For these folks, putting deliberate effort into change logs, release notes, and documentation feels wasteful.

My hunch is that this is due to a missing feedback loop: we are unlikely to get feedback about documentation, and more likely to get feedback on our project’s code.

My own writing improved after a past project had a strong feedback loop with my documentation’s intended audience. This has been so damn rare in my career, that it’s never surprising when I meet programmers who are uncomfortable with technical writing.

[GuB-42]

I think the reason programmers want to automate documentation is:

- they are programmers, automating things is their job, that's what they are good at, so of course they will do that

- there is the general "don't repeat yourself" idea. Documentation repeats the code so, ideally, if both are needed one should be generated from the other. Sometimes, the code can be generated from the documentation, but most of the times you can't, so documentation becomes secondary to the code.

[agateau]

I very much agree with this. Sometimes it's good to stop and think about what is lost when automating a task instead of doing it manually.