I think there are two types of documentation, one is for internal use by developers to build locally and maintain the internals of the system, and another is external/client facing documentation providing insights into how to call into the APIs and details about the APIs. I'll defer on external documentation as that can be broken up even further with publicly external (open to public), and internally external (document open to everyone within the org regardless of team). For external facing documentation, the most painful experience is when docs are outdated.

For internal documentation, the most memorable/painful instances I've encountered has been that the code is overly complex and I would have liked documentation to help me understand why we have so many parameters and configurations and their impact. I believe having more explicitly defined methods help reduce ambiguity within the code. I've seen many examples of methods or objects where the goal is avoid as much repeated code as possible which create these burdensome solutions, so it drives the responsibility on the clients and developers to understand how to configure the input to get the desired behavior. Often times, we don't need the multiple layers of abstraction or configuration just to consolidate everything into a method, I think it's fine to have multiple methods with explicit use cases. That helps developers read the code easier, understand what is happening, and is less mentally challenging. In my opinion, making the code easier to read will help reduce the need for extensive internal documentation besides the required onboarding, dev setup, and overall architecture designs.