Imagine you decided to learn a new programming language. You navigate to that language's website and you discover the documentation consists entirely of:
- “Getting Started”: sample code for Hello World
- “Advanced”: sample code for a Hello World that does a few fancy tricks
- If you're lucky, a list of the more important functions in the standard library,
- A link to the source and native documentation of the compiler/interpreter
You'd think that was a pretty shithouse state of affairs, right? Good programming language documentation introduces its major concepts one at a time, building up to a full understanding of the power of the language. Then it gives you a tour of the standard library, usually task-oriented to show you how common tasks of varying complexities can be performed. Then in the appendix you get the formal definition of the language, and comprehensive documentation of the libraries.
Unfortunately, despite the trend towards Domain Specific Languages running rampant, developers almost never seem to get the point that if this is indeed a language, it should be documented like one. Mostly, the attitude seems to be "Stack Overflow is thattaway."
End result: I spend a little too much of my time like this whenever I try to learn a new library or framework (Scala is a huge offender here).
Look, I get it. Domain Specific Languages are powerful. They create ways to express concepts in code that would otherwise be verbose or ugly. But with the power that comes from stepping outside the grammar and expectations of the host language, comes the fact that the tools and conventions developers are accustomed to in that language, the things they use every day to understand their code and the code of others, are also broken by your DSL.
If you're going to inflict a DSL on the world, at the barest of bare minimums you should:
- Have a properly specified grammar
- Fully document your keywords and operators
- Fully document your “standard library” in a format that is designed for the DSL itself, not by referring to the generated documentation of the language it was implemented in.
Each of these things will not only make your users happier, they will make your DSL better. You'll uncover all the wrinkles in your grammar that will trip up developers, all those places where your keywords or operators totally change meanings in different contexts, and all those weird inconsistencies in your libraries that are there because you're so used to seeing them from inside the interpreter looking out.
And I will have more time on weekends to watch Doctor Who with my wife instead of swearing at a screen trying to work out how to do something that would have been Really Simple if the developer hadn't decided that it would be so much cleverer to build an entirely new language to express it.
