Absolutely 100% agreed. I cannot go forth from documentation written by someone who assumes the verbage provided gives enough information in one place to make good use of it. Learning Perl is my one prime example, the documentation provided (once you're used to the semantics) is indispensible, but at times confusing, the examples provided are excellent but may not apply to the issue at hand. I found myself trying to find definitions for words used in the documentation. Feeling completely at odds with it, I found Perl Monks and the rest is history.

Examples of any kind are your friend, supply novice, intermediate and expert examples then try to mix it up. This may make your documentation larger but I think it would appeal to a larger audience.

BlackJudas