I am not a developer, I am a VP of Product. My role for my Digital Strategy Works clients and now for myself as a product owner of a WordPress plugin (Radio Station) is to ensure that the information architecture and user experience ensure we have mapped successful outcomes to user stories without the individual having to read any documentation or click on a tooltip to get more info about a feature or process.

If we're not creating the user experience that gets the user from A to B and they have to go and read the docs, then that's a fail in the sense that we're not completely thinking through how we can take the best approach and create a more usable product.

That being said, I completely agree with your thinking here in the sense that docs should really only be a fallback of last resort. But, I will say that having good documentation builds brand identity and brand equity. If you have a complete set of user docs that you keep updated, then you're going to generate positive feelings about your brand. So, while you may spend a lot of time thinking that the hours spend developing your docs is a waste of time, it's not in the sense that if you spend the time, what becomes visible to your customers is your commitment to the plugin or theme you've created.

I can't tell you how many times I've read docs by foreign plugin developers which failed to explain a feature or are outdated. That creates a negative impression of the brand and the developer. It says, if you can't keep up, then why should I invest in you and your plugin?

So, that's an important consideration that I think you left out of your post. What docs do for brand reputation. Because your reputation is important and if you fail to provide updated and complete docs, then you look amateur.

Damned if you do, damned if you don't. LOL.