[hinkley]

I wish I had a better phrase for "disagreeing by degrees", other than 'necessary, but insufficient'. You should write a user guide, but having a user guide doesn't provide anything other than a checkmark in a box somewhere.

What you should do is witness people using the documentation you provided. It's one of the most humbling experiences I've even willingly put myself through in a business setting, but the benefits are huge (can't say the same for some other experiences).

Without that you're in "something should be done, this is something, so we will do it" territory. You haven't proven anything until you can get a user through the docs without having to apologize a million times or dodge things being thrown at your head.

Critically, the quality of your code and product will improve, because you will discover that the emotional energy required to patiently apologize for some dumb limitation of your system is more expensive to you than the logistical energy of fixing the damned problem so you don't have to explain it.

We have the 5 Why's for production outages. For documentation, the 3 Why's are often sufficient for prioritizing fixing of bugs/misfeatures. This is part of the code is stupid because of Thing B. Thing B is that way because we cannot fix Thing C. Why can't we fix Thing C? No good (defensible) reason presents itself, or the reason is now gone. Well shit, let's fix it then, and put a paragraph in the release notes instead of the User Guide.