The thing that seems to come out of all these conversations is to treat documentation as UI/UX.
Maybe the problem is that it is treated as a secondary activity for developers, when it should be treated as a primary activity for writers.
We don't expect developers to be good at graphic design and even UI/UX design. In fact we should expect them to be terrible at it. A developer looks at the product from the inside, he sees classes, databases schemas, etc... not the way an end user will look at it. It means he will be biased into having a UI match the code structure and not the user workflow. There is a reason UI/UX designer is a job title, it is not a secondary activity for coders. Some can do both, but it is a different job.
Documentation could be treated the same way. Have people specialized in writing documentation. People who are actually good writers. I have seen it happen occasionally, and let me tell you, when you put a good writer (coding skills optional) in charge of writing documentation, the difference is night and day. Just as how better your UI will be when done by a good UI designer, and by a good UI designer, I mean someone who actually designs for usability, not someone who just tries to make something that looks cool for sales presentation, as it is too often the case for consumer apps today.
To me what's missing in many of these discussions is the cost/result calculation, how much effect is expected from "documentation". Thinking of it as an UX/UI could help put it more in terms of what time is spend by which user to achieve which specific task.
If specific use cases can be described, what needs to be written down becomes a lot more obvious and it can be done way more efficiently than just blindly "documenting" a system.
Maybe the problem is that it is treated as a secondary activity for developers, when it should be treated as a primary activity for writers.
We don't expect developers to be good at graphic design and even UI/UX design. In fact we should expect them to be terrible at it. A developer looks at the product from the inside, he sees classes, databases schemas, etc... not the way an end user will look at it. It means he will be biased into having a UI match the code structure and not the user workflow. There is a reason UI/UX designer is a job title, it is not a secondary activity for coders. Some can do both, but it is a different job.
Documentation could be treated the same way. Have people specialized in writing documentation. People who are actually good writers. I have seen it happen occasionally, and let me tell you, when you put a good writer (coding skills optional) in charge of writing documentation, the difference is night and day. Just as how better your UI will be when done by a good UI designer, and by a good UI designer, I mean someone who actually designs for usability, not someone who just tries to make something that looks cool for sales presentation, as it is too often the case for consumer apps today.