i've been working with man pages and software documentation for quite a long time. you're right that multiple passes through documentation are necessary.
however, when documentation gives little indication when variables are defined or are $null depending on which Event is being processed, then the documentation seems lacking some useful information. in my effort to assist improving a product I have spent money on, I offer the suggestion to note what is missing from the "on QUIT" and "on DISCONNECT" sections of the help file and request the adding of a mention of the usefulness of $chan(N) when processing those events.
in addition, I note in the "Remote" section of the help file, where it appears is a list of each event and links to 'examples and tips on how to use them', the event "DISCONNECT" is not present. If a link is added in that part of the help file, it would need only lead to the same place as the "CONNECT" link since at present they are documented together on one page.
as for this "me" level, it would seem the consensus is it is not a very useful feature (checking "if $nick == $me" is a substitute and is also more descriptive script-wise). Documenting it as "deprecated and marked for removal as of version X" may be in order?