Executable Documentation: From Documentation Languages to Purpose-Specific Languages.

We present executable documentation as a natural continuation of a long-term trend of documentation/code alignment that started with self-documenting code in the seventies (choice of meaningful naming), followed by literate programming (documentation embedded in code) and the dual where documentation embeds code as provided by Jupyter notebooks in the beginning of the new millennium. Executable documentation goes a step further by turning domain-specific notation and documentation languages typically used in the requirements and the design phase into fully-fledged modeling/programming languages. The resulting so-called Purpose-Specific Languages are meant to tighten the semantic gap, while directly covering the what , providing the how via automated transformation, and reduce the handwritten part to why the project is of importance. We will illustrate the impact of this approach in the DevOps scenario where we turn the graphical notation GitLab provides for documenting CI/CD workflows into an Integrated Modeling Environment called Rig. At a larger scale, Rig can be seen as part of our Language-Driven Engineering approach where it covers the aspect of CI/CD at the modeling level with a push-button link towards execution. This turns the corresponding running system into the ‘ultimate’ documentation where the understanding of all stakeholders should converge.