J-Spring 2023: Coding your documentation – Hubert Klein Ikkink

To write (technical) documentation usually means we leave our coding environment and for example need to start a word processor or open a wiki where we type our documentation. Especially when we (must) use word processor software a lot of things will distract us from writing content: we need to worry about formatting, styles and binary content. And when we want to include source code samples we need to copy/paste source code from an environment where it can be executed to static documentation. We will look at Asciidoctor as a tool which transforms documents written with Asciidoc, a Markdown-like markup, to HTML, Docbook and PDF. When we use the very simple Asciidoc markup we only focus on the content and structure of our documentation. And the really nice feature of Asciidoctor is that we can include the contents of external files, partially or completely, in the generated output. This means our documentation can reference source files that we know are correct, because we have written tests for those source files. Also because the markup is simply text we can simply see differences between versions using the tools we as developers are already familiar with. Asciidoctor has an extension API which allows us to add new functionality to Asciidoctor. This way we can also include diagrams described with text and generate graphical images from them. We can use Java as well to write extensions and we will see how we can write our own extensions.