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.

Comments

• Anonymous
  October 06, 2006
  "Larry, I almost wondered if you were under the impression that our tools generate parsers for textual DSLs?" Well... Yeah, I was under that impression. Or, at least, "(computer) language" is something that I interpret (heh!) in terms of grammars and tokens and so forth. ... I'm struggling to understand what I think you're suggesting, which is that your DSL approach may not be at all about what I think of as a computer language... Ultimately, do the MS tools produce a program? "DSL Tools primer for folks from a textual DSL background." I would suggest that the most likely "early adopters" for your tools are those of us who have a background in traditional text-based compiler techniques. So I really believe that a "Rosetta stone" primer (even just a blog entry or two...) would be very valuable.

• Anonymous
  October 06, 2006
  The comment has been removed