Struggling to find the way in?

Larry O'Brien is struggling to find his way in to our toolset and he's not finding our docs very helpful to him.

He makes a point that brought me up sharp:

"Microsoft's approach emphasizes the use of a Visio-like design surface to create some form of directed-acyclic graph. I think the result is a visualization of the grammar of the target language. But the documentation uses a  vocabulary different than standard "compiler 101" talk of tokens and lexemes and so forth, so I'm not sure.What the heck is a "relationship swimlane" and what does it have to do with language design and implementation? Is this vocabulary difference gratuitous or necessary? "

I'd simply never compared our terminology in any depth to that of compiler internals and compiler construction tools.  We've always been fairly concerned with trying to simplify some of the modeling (and particularly meta-modeling) terms by using the language of domain design.  We do tend to speak (within our team at least) about the domain model being an abstract syntax and the design surface being a concrete syntax; but that terminology hasn't really permeated to our docs.

Larry, I almost wondered if you were under the impression that our tools generate parsers for textual DSLs?  Do we give that impression? It would certainly be interesting to have a DSL Tools primer for folks from a textual DSL background.

We're also pushing to get more "why" and big picture into our docs.

Mind you, I'm fully aware that some of our terms are frankly impenetrable and you can blame me and Stuart for many of them - "RolePlayerLinkConnectDirective" is particularly awful, but it does represent a very abstract concept.