I've been scripting for 10+ years. When I started, I read the entirety of each text file, and help file before I even began. The help file is quite clear if the user actually reads it in the order it was meant to be read instead of skimming through it trying to figure out how to put pieces together.
Yes I do agree, the help file can, at times, be misleading but it's a help file for mIRC and it's features, not an "everything about everything for mIRC" file. Sometimes less is more when it comes to explaining things, especially to new users. mSL scripting is opened source and has a huge community on and off IRC, so if there's questions IMHO it'd be easier to find one of those outlets than to refer to a help file that can not be interacted with.
As for what should and shouldn't be documented; somethings are just too complicated to be explain in the help file(IE: Regular expressions), others are just too out of date to maintain documentation on when there is/are far superior methods($ifmatch vs. $v1/$v2)
I understand some things aren't as clear as they should be but you have to draw the line somewhere. I'd hate to be looking for, as an example, how to read a text file, and have to read through 9 pages of information to find what I needed.
mIRC's help file is short and to the point. It tells what a command can do, what an identifer returns, etc without overwhelming the user with information that isn't important or directly related to the topic. Yes it might take some fiddling to find what you need due to this but I'd rather it be a little unclear then have 9pages of information to go through.
