Executable documentation

Question

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?

Answer 1

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.

This isn't documentation so much as automating your workflow.

A simple web, wiki, or whatever page with a button linked to a script and text boxes for filling in x and y can do this. If you integrate your scripts with your code base or ticketing system you might be able to discover values for x and y automatically as well.

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

You can take it as far as makes sense to do so. Automating tedious repetitive processes isn't just good for your users. It's good for you. Just follow the 80 20 rule. Stick to automating the bulk of your repetitive work. Don't chase every corner case.

Is the overall goal realistic?

Yes if not taken to far. Expect to need to do some manual things.

Does anyone have experience with such an approach, or even best-practices?

Yes, it's typical to create many scripts to support a development environment.

How would you go about introducing something like that?

One script, one documentation page, at a time.

Answer 2

Is the overall goal realistic?

Yes. This is what people do today with Emacs using org-mode babel, even with access to documents on remote servers and integration between many different programming languages, as well as iterative code assembly with noweb-syntax.

But it will be a lot of work to make it good. Remember the extended 80/20 rule: 80% of people use only 20% of the features, but not the same 20%.

Does anyone have experience with such an approach, or even best-practices?

Don’t write complex programs. It is great for tutorials and instructions (at least that’s the experience from doing this for 5 years with Emacs org-mode).

You could also directly use Emacs org-mode instead of rolling your own. That’s the best practice I follow nowadays. I once favored Markdown over org-mode, but org-mode plainly wins in power.