Oh -- my comment was not intended to say anything about whether something ought to or could be mentioned in some additional places in the docs or not. The comment was meant to clear up the meaning of the attributes and what they do. I was under the impression that there may still be some subtle misconception about that.
On the structure of the docs: I'm sure there is room for improvement. However, with a reasonably complex language, it's neither practical nor possible to include everything in every context where it may apply under certain circumstances.
#1: High-level information intended to convey general principles (the "programming model") and language structure are available in the "Introduction", "Tutorials" and "How to" sections. Of course, it isn't possible to include every minute detail or special case etc. therein -- that would defeat the purpose.
#2: The real heart of the technical documentation is the "Language
Reference" which lists and links all applicable attributes, properties
and functions for every element (e.g. the language reference page for
the <trial> element links to the /responseframe,
/responseinterrupt etc. attributes).
So here's how the docs are intended to be used: For basics refer to #1. Once one has developed an understanding of the foundational concepts outlined in #1, refer to #2 for the specifics. At some point (the more experienced you get), you'll find yourself almost exclusively consulting #2 and only occasionally going back to #1.
People will have very different preferences regarding what they would like to see linked from where, mentioned in certain contexts etc. depending on their personal, concrete needs. Unfortunately satisfying those different preferences all at once seems intractable (at least to me).
Hence, for those specific questions, e.g. this forum exists as an apt space to ask them. I or others will answer them and/or point to additional resources such as the applicable language constructs / their documentation.
Hope this clarifies,
~Dave