By way of example, the K&R C book had a beautiful clarity and ability to fluidly move between the realms of reference, spec, and tutorial. If you're going to hold K&R C up as a model, you'd do well to mimic its documentation philosophy.
Actually the K&R equivalent for Hoon doesn't exist yet, and when it does it will be the first thing to read. Since it doesn't, the Arvo tutorial is the first thing to read:
http://www.urbit.org/2013/08/22/Chapter-1-arvo.html
But this itself is incomplete. Watch the video first:
Then build Arvo and use the sekrit code it generates to, basically, subscribe to our newsletter.
It's just a bad idea to document anything before it works completely, because you end up with doc that validates this criticism. The right way to build a language is to build it, use it, get comfortable with it, actually master it and become an expert of sorts... then document it. Sadly, not too many of us can live up to this ideal.
Very mindbending, got up to watching the video.
Am thinking it looks like it could be quite fast, I guess it would make sense to implement something like ContextFree in it as a start.
(Oops, fyolnish beat me to it.)
Too much hot air.