Making Executable Documentation a Reality with DSLs
A domain specific language (DSL) allows a development team to code in a language that business understands. In contrast to general purpose programming languages like Java, Ruby, or C#, a DSL is designed around a specific problem domain. This makes the syntax readable by technical and non-technical individuals alike. DSLs are usually built using a general purpose programming language, and their syntax tends to read more like spoken language.
Once a DSL parser is developed, it provides a new level of abstraction for developing applications. Applications or components are then written using the DSL syntax. One of the key values expressed in the Agile Manifesto is "working software over comprehensive documentation."
Documentation can be a source of excessive waste in an agile project due to the following:
- Documentation is not executable code, meaning that any time spent documenting could be spent implementing the solution.
- Documentation is difficult to rely on as it often trails the code in terms of correctness.
- Documentation must be updated when the code changes, otherwise it becomes out-of-date immediately.
- Unnecessary documentation is often created just to get a checkmark on the process list.
Yet, there are cases where documentation is a necessity due to the need to communicate complex requirements between the product owner and the development team. The insurance domain provides a great example as there are extensive rules that must be well understood by both the product owner and the development team. In these cases, a DSL provides a great alternative to traditional approaches to documentation.
Applications that use a DSL effectively become executable documentation. Some general purpose languages are more suited to the creation of a DSL. Dynamic languages like Ruby, Groovy, and Python tend to provide the flexibility needed to make code look more like spoken language.
There are even great tutorials that cover the creation of a DSL in Ruby or Groovy. Their loose syntax combined with dynamic capabilities like closures and code evaluation simplify the creation of a DSL. While the development of a DSL may require significant effort by the development team, certain domains make it well worth the effort.
If your project is suffering from the overhead of excessive documentation, consider the use of a DSL. It may increase your velocity by eliminating waste.
