Executable documentation

I like asciidoc, resp. asciidoctor, for documentation purposes. It is way better than MS Word and integrates better with source control compared to tools like Confluence.

Furthermore, I am aware of tools, which allow you to write executable parts within your asciidoc documentation. For example, PlantUML code can be included in the document and is executed to integrate the rendered image into the documentation. More towards my question, something like JQAssistant allows us to write executable rules as part of the documentation. This sort of literate programming is really nice to document your rules together with exactly those executing rules and helps a lot in not getting outdated documentation.

My question is not necessarily limited to asciidoc(tor), but inspired by the above. If there is a solution via asciidoc though, I’m quite interested to learn about it.

What I would like to be able to do is write company process documentations in a literate programming style that can be executed to support the documented process.

I think it’s best explained with an example or two:

• The documented process tells us that when starting a project, we have to fill out form X and place that in folder Y (or under version control, or whatever). Currently, this means that someone reads a PDF, then goes elsewhere to look for form X, copies it to her workspace, edits it, and then saves it to a newly-to-be-created folder Y. I would like to be able to instead directly execute the documentation such that the latest form X copy is placed into folder Y and maybe even an editor is directly opened.

• The documented process explains that a release has to be tagged and artifacts X,Y, and Z need to be placed into an archival folder F. Again, this can be done manually, or ideally, directly executed from that documentation.

My question boils down to two parts: Is something like that even available currently and if so, how far can we take that?

I can see several problematic limitations of course. For example, automatically tagging the above-mentioned release would require some sort of input (version number). You would further need a way to decide which parts of a lengthier documentation to execute, if for example, it contains both of the above descriptions.

Is the overall goal realistic? Does anyone have experience with such an approach, or even best-practices? How would you go about introducing something like that?