One of the paradoxes of documentation, and the teaching of many abstract topics, is that those with the most in-depth knowledge of the topic,are the least suitable to explain it, precisely because of that knowledge. They can't remember what it felt like not to know something, and they've usually learnt a jargon to simplify and speed discussions. That has to be filtered through 2 or 3 layers of ignorance before it's diluted to comprehensibility. If you don't know what you don't know, it's hard to plot a route to mastery. (On the other hand, more than one expert has said something like "the best way to learn a topic is to teach a course in it".)
In wanders the noob, and s/he is surrounded by weird words, some utterly new, which may or may not have their usual meanings if they aren't. It's hard to start exploring Wonderland when you don't even know how to ask the way to the rabbit hole. My impression of the Perl 6 documentation is that it was written by the designers and implementors, for their needs, a by-product of the development process. Since it's at the intersection of linguistics and computer science, the terminology tends to be a blend of both, seasoned with a pinch of local dialect. It's designed to answer questions like "what category of language is it?", "what programming paradigms does it favour?", "how is [some feature] designed?". For someone constructing a taxonomy of computer languages, or looking for interesting compiler techniques, it's great. That doesn't help the (English major) beginner who wants to find and fix incorrectly cased names in a file, or extract some data. It's also like the Unix documentation, an example-free zone. That assumes that the reader is skilled in converting abstract categories into explanatory examples for themselves, possibly one of the fundamental skills of programming. (It's much more natural to learn an abstract principle for re-use by having it explained through a concrete example.) I'm still trying to map a path into the jungle from practical daily treks, and it takes ruthless pruning of the language's features to avoid diversions and use of as-yet-unexplained features. (P5 can be tricky that way, too, but there's not as much to hide behind the curtain.) Trainee sales droids are taught not to mention "features", unless they can explain at least 2 "benefits" to the mark, (sorry, "prospect"). I'm going to start out with 5 ways to produce valid P6 that does absolutely nothing, and proceed from there. It'll be interesting to see if that approach works. (Apologies to Tom Browder for duplication; I had to edit the start of the message to make sense )
