Skip to main content
SpringerLink
Log in

Executable Documentation: From Documentation Languages to Purpose-Specific Languages

  • Conference paper
  • First Online:
Leveraging Applications of Formal Methods, Verification and Validation. Software Engineering (ISoLA 2022)

Part of the book series: Lecture Notes in Computer Science ((LNCS,volume 13702))

Included in the following conference series:

Abstract

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.

This is a preview of subscription content, log in via an institution to check access.

Access this chapter

Log in via an institution
Chapter
USD 29.95
Price excludes VAT (USA)
  • Available as PDF
  • Read on any device
  • Instant download
  • Own it forever
eBook
USD 59.99
Price excludes VAT (USA)
  • Available as EPUB and PDF
  • Read on any device
  • Instant download
  • Own it forever
Softcover Book
USD 79.99
Price excludes VAT (USA)
  • Compact, lightweight edition
  • Dispatched in 3 to 5 business days
  • Free shipping worldwide - see info

Tax calculation will be finalised at checkout

Purchases are for personal use only

Institutional subscriptions

Notes

  1. 1.

    https://gitlab.com/scce/cinco-cloud/-/pipelines/604982581.

  2. 2.

    Steffen et al. coined the term of mindset-supporting IDEs (mIDEs) as a special form of IMEs “that orchestrate the individual stakeholder-specific artifacts and aggregate them to a whole from which entire software systems are automatically generated” [36]. For the sake of simplicity, we will use the term IME in this paper.

  3. 3.

    https://en.wikipedia.org/wiki/Domain-specific_language.

  4. 4.

    https://www.springernature.com.

  5. 5.

    https://ocs.springer.com.

  6. 6.

    Besides time to restore and change fail percentage, lead time and deploy frequency are the key metrics of the DevOps Research and Assessment (DORA) [1] to evaluate DevOps performances.

  7. 7.

    We use human-friendly and human-readable synonymously here.

  8. 8.

    The project is open source and publicly available via GitLab: https://gitlab.com/scce/isola2022-pwn-example#1.

  9. 9.

    Targets is a feature that offers freely configurable parameters used to parameterize jobs, but it is out of scope of this Paper. Please cf. [40,41,42] for more detailed introduction.

References

  1. Explore DORA’s research program, https://www.devops-research.com/research.html. Accessed 8 Oct 2020

  2. Spring boot. https://spring.io/projects/spring-boot. Accessed 24 Jul 2022

  3. Aghajani, E.: Software documentation: automation and challenges. Ph.D. thesis, Università della Svizzera italiana (2020)

    Google Scholar 

  4. Allspaw, J., Hammond, P.: 10+ deploys per day: Dev and ops cooperation at Flickr. In: Velocity: Web Performance and Operations Conference, June 2009. https://www.youtube.com/watch?v=LdOe18KhtT4

  5. Beck, K., et al.: Manifesto for Agile Software Development. https://agilemanifesto.org (2001). Accessed 4 Mar 2014

  6. Ben-Kiki, O., Evans, C., döt Net, I.: YAML Ain’t Markup Language (YAML\(^{\rm TM}\)) Version 1.2. https://yaml.org/spec/1.2/spec.html (2009). Accessed 22 Jun 2021

  7. Boßelmann, S., et al.: DIME: a programming-less modeling environment for web applications. In: Margaria, T., Steffen, B. (eds.) ISoLA 2016. LNCS, vol. 9953, pp. 809–832. Springer, Cham (2016). https://doi.org/10.1007/978-3-319-47169-3_60

    Chapter  Google Scholar 

  8. Broy, M.: Object-oriented programming and software development–a critical assessment. In: In: McIver, A., Morgan, C. (eds.) Programming Methodology. Monographs in Computer Science, pp. 211–221. Springer, New York (2003). https://doi.org/10.1007/978-0-387-21798-7_10

  9. Chatley, R., Donaldson, A., Mycroft, A.: The next 7000 programming languages. In: Steffen, B., Woeginger, G. (eds.) Computing and Software Science. LNCS, vol. 10000, pp. 250–282. Springer, Cham (2019). https://doi.org/10.1007/978-3-319-91908-9_15

    Chapter  Google Scholar 

  10. Dagger: A portable devkit for ci/cd pipelines. https://dagger.io/. Accessed 27 July 2022

  11. Debois, P., et al.: DEVOPS: a software revolution in the making. J. Inf. Technol. Manag. 24(8), 3–39 (2011)

    Google Scholar 

  12. Dobing, B., Parsons, J.: Dimensions of UML diagram use: a survey of practitioners. J. Database Manage. (JDM) 19(1), 1–18 (2008)

    Article  Google Scholar 

  13. Forward, A., Lethbridge, T.C.: The relevance of software documentation, tools and technologies: a survey. In: Proceedings of the 2002 ACM Symposium on Document Engineering, pp. 26–33. DocEng 2002, Association for Computing Machinery, New York, NY, USA (2002). https://doi.org/10.1145/585058.585065

  14. Fowler, M.: Domain-specific languages guide. https://martinfowler.com/dsl.html. Accessed 06 Sept 2016

  15. Goldap, P., et al.: PG 601 - Bridging the Gap. Technical report, TU Dortmund (2017)

    Google Scholar 

  16. Gruber, J.: Markdown: Syntax. https://daringfireball.net/projects/markdown/syntax

  17. Hoare, C.A.: Hints on programming language design. Stanford Univ ca Dept of Computer Science, Technical report (1973)

    Google Scholar 

  18. Hurvitz, D.: Quotes via dan hurvitz. https://softwarequotes.com/author/via-dan-hurvitz. Accessed 20 July 2022

  19. Kelly, S., Tolvanen, J.P.: Domain-Specific Modeling: Enabling Full Code Generation. Wiley-IEEE Computer Society Press, Hoboken (2008). https://doi.org/10.1002/9780470249260

  20. Kluyver, T., et al.: Jupyter notebooks–a publishing format for reproducible computational workflows. In: Loizides, F., Scmidt, B. (eds.) Positioning and Power in Academic Publishing: Players, Agents and Agendas, pp. 87–90. IOS Press (2016). https://doi.org/10.3233/978-1-61499-649-1-87, https://eprints.soton.ac.uk/403913/

  21. Knuth, D.E.: Literate programming. Comput. J. 27(2), 97–111 (1984)

    Article  MATH  Google Scholar 

  22. Labouardy, M.: Pipeline as code: continuous delivery with Jenkins, Kubernetes, and terraform. Manning (2021). https://books.google.de/books?id=Lt9EEAAAQBAJ

  23. Madsen, O.L., Møller-Pedersen, B.: Using supplementary properties to reduce the need for documentation. In: Margaria, T., Steffen, B. (eds.) ISoLA 2022. LNCS, vol. 13702, pp. 35–59. Springer (2022)

    Google Scholar 

  24. Mellor, S.J., Balcer, M.J.: Executable UML: A Foundation for Model-Driven Architecture. Addison-Wesley Professional (2002)

    Google Scholar 

  25. Naujokat, S., Lybecait, M., Kopetzki, D., Steffen, B.: CINCO: a simplicity-driven approach to full generation of domain-specific graphical modeling tools. Software Tools for Technology Transfer 20(3), 327–354 (2017). https://doi.org/10.1007/s10009-017-0453-6

    Article  Google Scholar 

  26. Object Management Group (OMG): Documents associated with Object Constraint Language (OCL), Version 2.4 (2017). https://www.omg.org/spec/UML/2.5.1/. Accessed 08 Feb 209

  27. O’Connor, C.: The norway problem - why StrictYAML refuses to do implicit typing and so should you. https://hitchdev.com/strictyaml/why/implicit-typing-removed/. Accessed 3 Sept 2021

  28. Rangnau, T., Buijtenen, R.v., Fransen, F., Turkmen, F.: Continuous security testing: a case study on integrating dynamic security testing tools in ci/cd pipelines. In: 2020 IEEE 24th International Enterprise Distributed Object Computing Conference (EDOC), pp. 145–154 (2020). https://doi.org/10.1109/EDOC49727.2020.00026

  29. Shahin, M., Babar, M.A., Zhu, L.: Continuous integration, delivery and deployment: a systematic review on approaches, tools, challenges and practices. IEEE Access 5, 3909–3943 (2017). https://doi.org/10.1109/ACCESS.2017.2685629

    Article  Google Scholar 

  30. Smyth, S., et al.: Executable documentation: test-first in action. In: Margaria, T., Steffen, B. (eds.) ISoLA 2022. LNCS, vol. 13702, pp. 135–156. Springer (2022)

    Google Scholar 

  31. de St. Germain, H.J.: Commenting (jim’s cs topics). https://www.cs.utah.edu/~germain/PPS/Topics/commenting.html (2003), https://www.cs.utah.edu/~germain/PPS/Topics/commenting.html. Accessed 22 Jul 2022

  32. Stallings, A.E.: After a Greek proverb. Poetry 199(4), 299–299 (2012)

    Google Scholar 

  33. Steffen, B.: Inter- & intradepartmental knowledge management barriers when offering single unit solutions (2016). https://essay.utwente.nl/70224/

  34. Steffen, B., Howar, F., Tegeler, T., Steffen, B.: Agile business engineering: from transformation towards continuousinnovation. In: Margaria, T., Steffen, B. (eds.) ISoLA 2021. LNCS, vol. 13036, pp. 77–94. Springer, Cham (2021). https://doi.org/10.1007/978-3-030-89159-6_6

    Chapter  Google Scholar 

  35. Steffen, B., Steffen, B.: Asking why. In: Margaria, T., Steffen, B. (eds.) Leveraging Applications of Formal Methods, Verification and Validation, pp. 55–67. Springer International Publishing, Cham (2021)

    Chapter  Google Scholar 

  36. Steffen, B., Gossen, F., Naujokat, S., Margaria, T.: Language-driven engineering: from general-purpose to purpose-specific languages. In: Steffen, B., Woeginger, G. (eds.) Computing and Software Science. LNCS, vol. 10000, pp. 311–344. Springer, Cham (2019). https://doi.org/10.1007/978-3-319-91908-9_17

    Chapter  Google Scholar 

  37. Steffen, B., Narayan, P.: Full life-cycle support for end-to-end processes. IEEE Comput. 40(11), 64–73 (2007). https://doi.org/10.1109/MC.2007.386

    Article  Google Scholar 

  38. Stevens, P.: Models as documents, documents as models. In: Margaria, T., Steffen, B. (eds.) ISoLA 2022. LNCS, vol. 13702, pp. 28–34. Springer (2022)

    Google Scholar 

  39. Sugiyama, K., Tagawa, S., Toda, M.: Methods for visual understanding of hierarchical system structures. IEEE Trans. Syst. Man Cybern. 11(2), 109–125 (1981)

    Article  MathSciNet  Google Scholar 

  40. Tegeler, T., Gossen, F., Steffen, B.: A model-driven approach to continuous practices for modern cloud-based web applications. In: 2019 9th International Conference on Cloud Computing, Data Science Engineering (Confluence), pp. 1–6 (2019). https://doi.org/10.1109/CONFLUENCE.2019.8776962

  41. Tegeler, T., Teumert, S., Schürmann, J., Bainczyk, A., Busch, D., Steffen, B.: An Introduction to graphical modeling of CI/CD Workflows with rig. In: Margaria, T., Steffen, B. (eds.) ISoLA 2021. LNCS, vol. 13036, pp. 3–17. Springer, Cham (2021). https://doi.org/10.1007/978-3-030-89159-6_1

    Chapter  Google Scholar 

  42. Teumert, S.: Rig | low-code ci/cd modeling. https://scce.gitlab.io/rig/. Accessed 07 Jan 2022

  43. Toghraei, M.: Piping and Instrumentation Diagram Development. Wiley (2019). https://books.google.de/books?id=ICONDwAAQBAJ

  44. Wortmann, N.: Modellbasierte Modellierung von industriellen Zentrifugen mit Codegenerierung für Steuerungssysteme. Bachelor thesis, Münster University of Applied Sciences (2015)

    Google Scholar 

  45. Wortmann, N., Michel, M., Naujokat, S.: A fully model-based approach to software development for industrial centrifuges. In: Margaria, T., Steffen, B. (eds.) ISoLA 2016. LNCS, vol. 9953, pp. 774–783. Springer, Cham (2016). https://doi.org/10.1007/978-3-319-47169-3_58

    Chapter  Google Scholar 

  46. Zampetti, F., Geremia, S., Bavota, G., Di Penta, M.: Ci/cd pipelines evolution and restructuring: a qualitative and quantitative study. In: 2021 IEEE International Conference on Software Maintenance and Evolution (ICSME),. pp. 471–482 (2021). https://doi.org/10.1109/ICSME52107.2021.00048

  47. Zweihoff, P.: Aligned and collaborative language-driven engineering. Dissertation, TU Dortmund, Dortmund, Germany (2022). https://doi.org/10.17877/DE290R-22594, https://eldorado.tu-dortmund.de/handle/2003/40736

  48. Zweihoff, P., Tegeler, T., Schürmann, J., Bainczyk, A., Steffen, B.: Aligned, purpose-driven cooperation: the future way of system development. In: Margaria, T., Steffen, B. (eds.) ISoLA 2021. LNCS, vol. 13036, pp. 426–449. Springer, Cham (2021). https://doi.org/10.1007/978-3-030-89159-6_27

    Chapter  Google Scholar 

Download references

Author information

Authors and Affiliations

  1. Chair for Programming Systems, TU Dortmund University, Dortmund, Germany

    Tim Tegeler, Steve Boßelmann, Jonas Schürmann, Steven Smyth, Sebastian Teumert & Bernhard Steffen

Authors
  1. Tim Tegeler
    View author publications

    You can also search for this author in PubMed Google Scholar

  2. Steve Boßelmann
    View author publications

    You can also search for this author in PubMed Google Scholar

  3. Jonas Schürmann
    View author publications

    You can also search for this author in PubMed Google Scholar

  4. Steven Smyth
    View author publications

    You can also search for this author in PubMed Google Scholar

  5. Sebastian Teumert
    View author publications

    You can also search for this author in PubMed Google Scholar

  6. Bernhard Steffen
    View author publications

    You can also search for this author in PubMed Google Scholar

Corresponding author

Correspondence to Tim Tegeler .

Editor information

Editors and Affiliations

  1. University of Limerick, CSIS and Lero, Limerick, Ireland

    Tiziana Margaria

  2. TU Dortmund, Dortmund, Germany

    Bernhard Steffen

Rights and permissions

Reprints and permissions

Copyright information

© 2022 The Author(s), under exclusive license to Springer Nature Switzerland AG

About this paper

Check for updates. Verify currency and authenticity via CrossMark

Cite this paper

Tegeler, T., Boßelmann, S., Schürmann, J., Smyth, S., Teumert, S., Steffen, B. (2022). Executable Documentation: From Documentation Languages to Purpose-Specific Languages. In: Margaria, T., Steffen, B. (eds) Leveraging Applications of Formal Methods, Verification and Validation. Software Engineering. ISoLA 2022. Lecture Notes in Computer Science, vol 13702. Springer, Cham. https://doi.org/10.1007/978-3-031-19756-7_10

Download citation

  • DOI: https://doi.org/10.1007/978-3-031-19756-7_10

  • Published:

  • Publisher Name: Springer, Cham

  • Print ISBN: 978-3-031-19755-0

  • Online ISBN: 978-3-031-19756-7

  • eBook Packages: Computer ScienceComputer Science (R0)

Publish with us

Policies and ethics

Search

Navigation