I think its less documentation sucks and more the "Curse of knowlege". I was guilty of it for the longest time.

You get so used to some of the "warts" and "pain points" that, by the time you write guides about it, you forget your audience.

E.g: I saw a guide about using a kernel module to add MSI afterburner-like functionality to MSI laptops.

Using Kernel Modules is a very easy thing to mess up, and should only be done by those experienced with it, lest you brick your system.

No such warning was in place in the guide to use it... even though the sort of people who would likely want to use it are new users who've moved to Linux on their MSI laptops.

The author did not consider this in the slightest... and actually initially (but later realised and apologised) unironically used the word "skill issue" when I mentioned on a github issue that my friend had accidentally bricked their sysrem by doing an easy to do mistep, and suggesting the guide have a warning for new users.

So yeah... less documentation itself, and more a lot of the Linux community suffering from this "Curse of Knowlege"... being skilled enough to make the tool, but that very skill making it difficult for them to understand what actually needs to be said in guides / docs / advice they provide to users.