Sometimes it's not even rare that documentation is wrong. The documentation for a vendor who I won't name - but might be at Series J and worth north or $50 billion - seems to be wrong more often than it's right.

We frequently say, don't blame the tools, it's you. That pushes "blame the tools" outside of the Overton window, and when we need to blame a tool, we're looked at like we have five heads.

Ten years ago, I was dealing with a bizarre problem in RHEL where we'd stand up an EC2 instance with 4GB of memory, have 4.4GB of memory reported to the system, and be able to use 3.6GB of it. I spent _a long_ time trying to figure out what was going on. (This was around the time we started using Node.js at that company, and needed 4GB of RAM just for Jenkins to run Webpack, and we couldn't justify the expensive of 8GB nodes.)

I did a deep dive into how the BIOS advertises memory to the system, how Linux maps it, and so forth, before finally filing a bug with Red Hat. 36 hours later, they identified a commit in the upstream kernel, which they forgot to cherry-pick into the RHEL kernel.

That's a very human mistake, and not one I dreamed the humans at Red Hat - the ones far smarter than me, making far more money than me - could ever make! Yet here we were, and I'd wasted a bunch of time convinced that a support ticket was not the right way to go.

> Yet here we were, and I'd wasted a bunch of time convinced that a support ticket was not the right way to go.

From my experiences with public issue trackers for big projects, it's very reasonable to postpone creating a new issue, and rather follow my own hypothesis/solution first:

* creating a new issue takes significant effort to be concise, provide examples, add annotated screenshots, follow the reporting template, etc., in hopes of convincing the project members that the issue is worth their time.

Failing to do so often results in project members not understanding or misunderstanding the problem, and all too often leads to them directly closing the issue.

And even when reporting a well-written issue, it can still just be ignored/stall, and be autoclosed by GitHubBot.

In my case, it was egregiously bad, because someone had cribbed docs from an entirely separate scripting language that did almost the same things. Most of the same features were there, but the docs were utter lies, and failures were silent. So you'd go down the wrong branch of an if statement because it wasn't checking the conditions it claimed to check.

Once I started actually testing the scripts against the docs and rewriting them, life got so much better. The worst part is that it had been that way for years and somehow nobody noticed because the people using that horrible scripting language mostly weren't programmers and they'd just tweak things until they could happy path just enough to kinda-sorta work.